From 5a5c21afc3e107e97273b2e6316b579ac203d30e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 1 Mar 2023 14:06:13 +0100
Subject: [PATCH 01/49] Few fixes and additions to useListbox

---
 docs/pages/experiments/base/listbox.tsx       | 220 ++++++++++++++++++
 .../MenuUnstyled/useMenuChangeNotifiers.ts    |   2 +-
 .../useListbox/defaultListboxReducer.test.ts  |  19 ++
 .../src/useListbox/defaultListboxReducer.ts   |  68 +++++-
 packages/mui-base/src/useListbox/index.ts     |   1 +
 .../src/useListbox/useControllableReducer.ts  |   3 +-
 .../src/useListbox/useListChangeNotifiers.ts  |  68 ++++++
 .../mui-base/src/useListbox/useListbox.ts     | 195 +++++++++++++++-
 .../src/useListbox/useListbox.types.ts        |  14 ++
 .../src/useSelect/useSelectChangeNotifiers.ts |   4 +-
 packages/mui-base/src/utils/useMessageBus.ts  |  10 +-
 11 files changed, 576 insertions(+), 28 deletions(-)
 create mode 100644 docs/pages/experiments/base/listbox.tsx
 create mode 100644 packages/mui-base/src/useListbox/useListChangeNotifiers.ts

diff --git a/docs/pages/experiments/base/listbox.tsx b/docs/pages/experiments/base/listbox.tsx
new file mode 100644
index 00000000000000..1ea7e10fbd0374
--- /dev/null
+++ b/docs/pages/experiments/base/listbox.tsx
@@ -0,0 +1,220 @@
+/* eslint-disable react/no-danger */
+import * as React from 'react';
+import clsx from 'clsx';
+import useListbox, { ListContext, useListItem } from '@mui/base/useListbox';
+
+const styles = `
+  body {
+    padding: 0;
+    margin: 0;
+    font-family: IBM Plex Sans, sans-serif;
+  }
+
+  .list {
+    display: flex;
+    gap: 16px;
+    align-items: center;
+    justify-content: flex-start;
+    max-height: 70vh;
+    padding: 16px;
+    width: 100vw;
+    flex-wrap: wrap;
+    background: linear-gradient(-30deg, #009245, #FCEE21);
+    box-sizing: border-box;
+    margin: 0;
+  }
+
+  .list:focus-visible {
+    outline: none;
+  }
+  
+  .item {
+    width: 50px;
+    height: 50px;
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid rgba(255, 255, 255, 0.3);
+    border-radius: 4px;
+    box-sizing: border-box;
+    background: linear-gradient(-30deg, #f5f5f5, #fff);
+    font-size: 18px;
+    color: #333;
+    user-select: none;
+    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.1), 0 4px 4px -2px rgba(0, 0, 0, 0.15);
+  }
+
+  .item.highlighted:not([tabindex]),
+  .item:focus-visible
+   {
+    outline: 2px solid #fff;
+    outline-offset: 4px;
+  }
+
+  .item.selected {
+    background: linear-gradient(-30deg, #363636, #666);
+    color: #fff;
+  }
+
+  .controls {
+    padding: 16px;
+  }
+
+  .controls > div {
+    margin-bottom: 8px;
+  }
+
+  .controls button {
+    border: 1px solid #999;
+    background: #fff;
+    padding: 8px 16px;
+    border-radius: 4px;
+    font-family: inherit;
+    margin: 0 4px;
+    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.1), 0 4px 4px -2px rgba(0, 0, 0, 0.15);
+  }
+
+  .controls button.active {
+    background: #73bc34;
+    color: #fff;
+  }
+
+  .state {
+    padding: 16px;
+    background: #202020;
+    color: #fff;
+  }`;
+
+const items = Array.from({ length: 200 }, (_, i) => i + 1);
+
+const Item = React.forwardRef(function Item(
+  props: React.PropsWithChildren<{ value: number }>,
+  ref: React.Ref<HTMLElement>,
+) {
+  const item = props.value;
+  const { getItemProps, getItemState } = useListItem({ item, ref });
+
+  const itemProps = getItemProps();
+  const state = getItemState();
+
+  const classes = clsx('item', {
+    highlighted: state.highlighted,
+    selected: state.selected,
+  });
+
+  return (
+    <div {...itemProps} className={classes}>
+      {item}
+    </div>
+  );
+});
+
+function List() {
+  const [orientation, setOrientation] = React.useState<
+    'horizontal-ltr' | 'horizontal-rtl' | 'vertical'
+  >('horizontal-ltr');
+  const [focusManagement, setFocusManagement] = React.useState<'activeDescendant' | 'DOM'>(
+    'activeDescendant',
+  );
+
+  let flexDirection: React.CSSProperties['flexDirection'];
+  switch (orientation) {
+    case 'horizontal-ltr':
+      flexDirection = 'row';
+      break;
+    case 'horizontal-rtl':
+      flexDirection = 'row-reverse';
+      break;
+    default:
+      flexDirection = 'column';
+      break;
+  }
+
+  const itemRefs = React.useRef(new Map<number, HTMLElement>());
+  const listbox = useListbox({
+    options: items,
+    getOptionElement: (item) => itemRefs.current.get(item) || null,
+    orientation,
+    focusManagement,
+    selectionLimit: 1,
+  });
+
+  const { getRootProps, contextValue, selectedOptions, highlightedOption } = listbox;
+
+  const handleItemRef = React.useCallback((item: number, node: HTMLElement | null) => {
+    if (node) {
+      itemRefs.current.set(item, node);
+    } else {
+      itemRefs.current.delete(item);
+    }
+  }, []);
+
+  return (
+    <React.Fragment>
+      <div className="controls">
+        <div>
+          Orientation:&nbsp;
+          <button
+            type="button"
+            onClick={() => setOrientation('horizontal-ltr')}
+            className={orientation === 'horizontal-ltr' ? 'active' : ''}
+          >
+            horizontal-ltr
+          </button>
+          <button
+            type="button"
+            onClick={() => setOrientation('horizontal-rtl')}
+            className={orientation === 'horizontal-rtl' ? 'active' : ''}
+          >
+            horizontal-rtl
+          </button>
+          <button
+            type="button"
+            onClick={() => setOrientation('vertical')}
+            className={orientation === 'vertical' ? 'active' : ''}
+          >
+            vertical
+          </button>
+        </div>
+        <div>
+          Focus management:&nbsp;
+          <button
+            type="button"
+            onClick={() => setFocusManagement('activeDescendant')}
+            className={focusManagement === 'activeDescendant' ? 'active' : ''}
+          >
+            activeDescendant
+          </button>
+          <button
+            type="button"
+            onClick={() => setFocusManagement('DOM')}
+            className={focusManagement === 'DOM' ? 'active' : ''}
+          >
+            DOM
+          </button>
+        </div>
+      </div>
+      <div className="state">
+        <pre>Selected: {selectedOptions.join(', ')}</pre>
+        <pre>Highlighted: {highlightedOption ?? '(none)'}</pre>
+      </div>
+      <div {...getRootProps()} className="list" style={{ flexDirection }}>
+        <ListContext.Provider value={contextValue}>
+          {items.map((item) => (
+            <Item key={item} value={item} ref={(node) => handleItemRef(item, node)} />
+          ))}
+        </ListContext.Provider>
+      </div>
+    </React.Fragment>
+  );
+}
+
+export default function Demo() {
+  return (
+    <React.Fragment>
+      <style dangerouslySetInnerHTML={{ __html: styles }} />
+      <List />
+    </React.Fragment>
+  );
+}
diff --git a/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts b/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
index ed4bc97edd1849..fe4b8c5e090c0e 100644
--- a/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
+++ b/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import useMessageBus from '../utils/useMessageBus';
 
-const HIGHLIGHT_CHANGE_TOPIC = 'menu:change-highlight';
+const HIGHLIGHT_CHANGE_TOPIC = Symbol('menu:change-highlight');
 
 export interface MenuChangeNotifiers {
   /**
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
index 13a1973b05d882..31b6021d81d139 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
@@ -22,6 +22,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -47,6 +48,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -73,6 +75,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
         option: 'two',
@@ -98,6 +101,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: 1,
         },
         option: 'two',
@@ -123,6 +127,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
         option: 'two',
@@ -148,6 +153,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
         option: 'two',
@@ -178,6 +184,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: (_, index) => index === 0,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -206,6 +213,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: (_, index) => index === 4,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -234,6 +242,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: (_, index) => index === 0 || index === 4,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -262,6 +271,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: (_, index) => index === 0 || index === 4,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -288,6 +298,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: () => true,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -316,6 +327,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: () => false,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
         };
@@ -342,6 +354,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: () => false,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: 1,
           },
         };
@@ -368,6 +381,7 @@ describe('useListbox defaultReducer', () => {
             isOptionDisabled: () => false,
             optionComparer: (o, v) => o === v,
             optionStringifier: (option) => option,
+            orientation: 'vertical',
             selectionLimit: null,
           },
           option: 'two',
@@ -397,6 +411,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -422,6 +437,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -447,6 +463,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: (_, i) => i === 1,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -472,6 +489,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: (_, i) => i === 1,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
@@ -497,6 +515,7 @@ describe('useListbox defaultReducer', () => {
           isOptionDisabled: () => false,
           optionComparer: (o, v) => o === v,
           optionStringifier: (option) => option,
+          orientation: 'vertical',
           selectionLimit: null,
         },
       };
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
index 53574523f4feb3..13e64d318996b6 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
@@ -217,6 +217,7 @@ function handleKeyDown<TOption>(
   parameters: UseListboxParametersWithDefaults<TOption>,
 ): ListboxState<TOption> {
   const previouslySelectedValue = state.highlightedValue;
+  const { orientation } = parameters;
 
   switch (event.key) {
     case 'Home':
@@ -244,19 +245,51 @@ function handleKeyDown<TOption>(
       };
 
     case 'ArrowUp':
-      // TODO: extend current selection with Shift modifier
+      if (orientation !== 'vertical') {
+        break;
+      }
+
       return {
         ...state,
         highlightedValue: moveHighlight(previouslySelectedValue, -1, parameters),
       };
 
     case 'ArrowDown':
-      // TODO: extend current selection with Shift modifier
+      if (orientation !== 'vertical') {
+        break;
+      }
+
       return {
         ...state,
         highlightedValue: moveHighlight(previouslySelectedValue, 1, parameters),
       };
 
+    case 'ArrowLeft': {
+      if (orientation === 'vertical') {
+        break;
+      }
+
+      const offset = orientation === 'horizontal-ltr' ? -1 : 1;
+
+      return {
+        ...state,
+        highlightedValue: moveHighlight(previouslySelectedValue, offset, parameters),
+      };
+    }
+
+    case 'ArrowRight': {
+      if (orientation === 'vertical') {
+        break;
+      }
+
+      const offset = orientation === 'horizontal-ltr' ? 1 : -1;
+
+      return {
+        ...state,
+        highlightedValue: moveHighlight(previouslySelectedValue, offset, parameters),
+      };
+    }
+
     case 'Enter':
     case ' ':
       if (state.highlightedValue === null) {
@@ -272,7 +305,14 @@ function handleKeyDown<TOption>(
   return state;
 }
 
-function handleBlur<TOption>(state: ListboxState<TOption>): ListboxState<TOption> {
+function handleBlur<TOption>(
+  state: ListboxState<TOption>,
+  props: UseListboxParametersWithDefaults<TOption>,
+): ListboxState<TOption> {
+  if (props.focusManagement === 'DOM') {
+    return state;
+  }
+
   return {
     ...state,
     highlightedValue: null,
@@ -357,15 +397,21 @@ function handleTextNavigation<TOption>(
 
 function handleOptionsChange<TOption>(
   options: TOption[],
+  previousOptions: TOption[],
   state: ListboxState<TOption>,
   props: UseListboxParametersWithDefaults<TOption>,
 ): ListboxState<TOption> {
-  const { optionComparer } = props;
+  const { optionComparer, focusManagement } = props;
 
-  const newHighlightedOption =
-    state.highlightedValue == null
-      ? null
-      : options.find((option) => optionComparer(option, state.highlightedValue!)) ?? null;
+  let newHighlightedOption: TOption | null = null;
+
+  if (state.highlightedValue != null) {
+    newHighlightedOption =
+      options.find((option) => optionComparer(option, state.highlightedValue!)) ?? null;
+  } else if (focusManagement === 'DOM' && previousOptions.length === 0) {
+    // TODO: exclude disabled options
+    newHighlightedOption = options[0] ?? null;
+  }
 
   // exclude selected values that are no longer in the options
   const selectedValues = state.selectedValues ?? [];
@@ -385,13 +431,15 @@ export default function defaultListboxReducer<TOption>(
 ): Readonly<ListboxState<TOption>> {
   const { type } = action;
 
+  console.log('reducer called', type, action);
+
   switch (type) {
     case ActionTypes.keyDown:
       return handleKeyDown(action.event, state, action.props);
     case ActionTypes.optionClick:
       return handleOptionSelection(action.option, state, action.props);
     case ActionTypes.blur:
-      return handleBlur(state);
+      return handleBlur(state, action.props);
     case ActionTypes.setValue:
       return {
         ...state,
@@ -405,7 +453,7 @@ export default function defaultListboxReducer<TOption>(
     case ActionTypes.textNavigation:
       return handleTextNavigation(state, action.searchString, action.props);
     case ActionTypes.optionsChange:
-      return handleOptionsChange(action.options, state, action.props);
+      return handleOptionsChange(action.options, action.previousOptions, state, action.props);
     default:
       return state;
   }
diff --git a/packages/mui-base/src/useListbox/index.ts b/packages/mui-base/src/useListbox/index.ts
index 501d7efb93ea07..7f76c2e2e7eeb1 100644
--- a/packages/mui-base/src/useListbox/index.ts
+++ b/packages/mui-base/src/useListbox/index.ts
@@ -1,4 +1,5 @@
 export { default } from './useListbox';
+export * from './useListbox';
 export { default as defaultListboxReducer } from './defaultListboxReducer';
 
 export * from './useListbox.types';
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.ts b/packages/mui-base/src/useListbox/useControllableReducer.ts
index 81e5240fb2e299..75fa1aa35123c6 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.ts
+++ b/packages/mui-base/src/useListbox/useControllableReducer.ts
@@ -75,7 +75,7 @@ function useStateChangeDetection<TOption>(
     const nextSelectedValues = nextState.selectedValues as TOption[];
 
     if (!areArraysEqual(nextSelectedValues, previousSelectedValues, optionComparer)) {
-      onChange?.(lastActionRef.current.event, nextSelectedValues);
+      onChange?.(lastActionRef.current.event, nextSelectedValues, lastActionRef.current.type);
     }
 
     // Fires the highlightChange event when reducer returns changed `highlightedValue`.
@@ -89,6 +89,7 @@ function useStateChangeDetection<TOption>(
       propsRef.current?.onHighlightChange?.(
         lastActionRef.current.event,
         nextState.highlightedValue,
+        lastActionRef.current.type,
       );
     }
 
diff --git a/packages/mui-base/src/useListbox/useListChangeNotifiers.ts b/packages/mui-base/src/useListbox/useListChangeNotifiers.ts
new file mode 100644
index 00000000000000..988ac15c28117b
--- /dev/null
+++ b/packages/mui-base/src/useListbox/useListChangeNotifiers.ts
@@ -0,0 +1,68 @@
+import * as React from 'react';
+import useMessageBus from '../utils/useMessageBus';
+
+const SELECTION_CHANGE_TOPIC = Symbol('change-selection');
+const HIGHLIGHT_CHANGE_TOPIC = Symbol('change-highlight');
+
+export interface ListChangeNotifiers<TValue> {
+  /**
+   * Calls all the registered selection change handlers.
+   *
+   * @param newValue - The newly selected value(s).
+   */
+  notifySelectionChanged: (newValue: TValue[]) => void;
+  /**
+   * Calls all the registered highlight change handlers.
+   *
+   * @param newValue - The newly highlighted value.
+   */
+  notifyHighlightChanged: (newValue: TValue | null) => void;
+
+  registerSelectionChangeHandler: (handler: (newValue: TValue[]) => void) => () => void;
+
+  registerHighlightChangeHandler: (handler: (newValue: TValue | null) => void) => () => void;
+}
+
+/**
+ * @ignore - internal hook.
+ *
+ * This hook is used to notify any interested components about changes in the Select's selection and highlight.
+ */
+export default function useSelectChangeNotifiers<Item>(): ListChangeNotifiers<Item> {
+  const messageBus = useMessageBus();
+
+  const notifySelectionChanged = React.useCallback(
+    (newSelectedItems: Item | Item[] | null) => {
+      messageBus.publish(SELECTION_CHANGE_TOPIC, newSelectedItems);
+    },
+    [messageBus],
+  );
+
+  const notifyHighlightChanged = React.useCallback(
+    (newHighlightedItem: Item | null) => {
+      messageBus.publish(HIGHLIGHT_CHANGE_TOPIC, newHighlightedItem);
+    },
+    [messageBus],
+  );
+
+  const registerSelectionChangeHandler = React.useCallback(
+    (handler: (newSelectedItems: Item[]) => void) => {
+      return messageBus.subscribe(SELECTION_CHANGE_TOPIC, handler);
+    },
+    [messageBus],
+  );
+
+  const registerHighlightChangeHandler = React.useCallback(
+    (handler: (newHighlightedItem: Item | null) => void) => {
+      return messageBus.subscribe(HIGHLIGHT_CHANGE_TOPIC, handler);
+    },
+    [messageBus],
+  );
+
+  return {
+    notifySelectionChanged,
+    notifyHighlightChanged,
+    registerSelectionChangeHandler,
+    registerHighlightChangeHandler,
+  };
+}
diff --git a/packages/mui-base/src/useListbox/useListbox.ts b/packages/mui-base/src/useListbox/useListbox.ts
index d9883acf3d2586..036a20594e5569 100644
--- a/packages/mui-base/src/useListbox/useListbox.ts
+++ b/packages/mui-base/src/useListbox/useListbox.ts
@@ -14,12 +14,27 @@ import areArraysEqual from '../utils/areArraysEqual';
 import { EventHandlers } from '../utils/types';
 import useLatest from '../utils/useLatest';
 import useTextNavigation from '../utils/useTextNavigation';
+import useForcedRerendering from '../utils/useForcedRerendering';
+import useListChangeNotifiers from './useListChangeNotifiers';
 
 const defaultOptionComparer = <TOption>(optionA: TOption, optionB: TOption) => optionA === optionB;
 const defaultIsOptionDisabled = () => false;
 const defaultOptionStringifier = <TOption>(option: TOption) =>
   typeof option === 'string' ? option : String(option);
 
+export interface ListContextValue<Item> {
+  getItemProps: <TOther extends EventHandlers = {}>(
+    item: Item,
+    otherHandlers?: TOther,
+  ) => UseListboxOptionSlotProps<TOther>;
+  getItemState: (item: Item) => OptionState;
+  registerHighlightChangeHandler: (handler: (item: Item | null) => void) => () => void;
+  registerSelectionChangeHandler: (handler: (items: Item | Item[] | null) => void) => () => void;
+  focusManagement: UseListboxParameters<Item>['focusManagement'];
+}
+
+export const ListContext = React.createContext<ListContextValue<any> | null>(null);
+
 /**
  * @ignore - internal hook.
  *
@@ -35,9 +50,12 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     id: idProp,
     isOptionDisabled = defaultIsOptionDisabled,
     listboxRef: externalListboxRef,
+    onHighlightChange,
     optionComparer = defaultOptionComparer,
     optionStringifier = defaultOptionStringifier,
     options,
+    getOptionElement,
+    orientation = 'vertical',
     stateReducer: externalReducer,
     value: valueParam,
     selectionLimit = null,
@@ -52,6 +70,30 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
   const optionIdGenerator = props.optionIdGenerator ?? defaultIdGenerator;
 
+  const listboxRef = React.useRef<HTMLUListElement>(null);
+  const handleRef = useForkRef(externalListboxRef, listboxRef);
+
+  const handleHighlightChange = React.useCallback(
+    (
+      event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
+      value: TOption | null,
+      reason: ActionTypes,
+    ) => {
+      onHighlightChange?.(event, value, reason);
+
+      if (
+        focusManagement === 'DOM' &&
+        value != null &&
+        (reason === ActionTypes.optionClick ||
+          reason === ActionTypes.keyDown ||
+          reason === ActionTypes.textNavigation)
+      ) {
+        getOptionElement?.(value)?.focus();
+      }
+    },
+    [getOptionElement, onHighlightChange, focusManagement],
+  );
+
   const propsWithDefaults: React.RefObject<UseListboxParametersWithDefaults<TOption>> = useLatest(
     {
       ...props,
@@ -59,16 +101,15 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
       disableListWrap,
       focusManagement,
       isOptionDisabled,
+      onHighlightChange: handleHighlightChange,
       optionComparer,
       optionStringifier,
+      orientation,
       selectionLimit,
     },
     [props],
   );
 
-  const listboxRef = React.useRef<HTMLUListElement>(null);
-  const handleRef = useForkRef(externalListboxRef, listboxRef);
-
   const [{ highlightedValue, selectedValues: selectedValue }, dispatch] = useControllableReducer(
     defaultReducer,
     externalReducer,
@@ -103,6 +144,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   // introducing refs to avoid recreating the getOptionState function on each change.
   const latestSelectedValue = useLatest(selectedValue);
   const latestHighlightedIndex = useLatest(highlightedIndex);
+  const latestHighlightedValue = useLatest(highlightedValue);
   const previousOptions = React.useRef<TOption[]>([]);
 
   React.useEffect(() => {
@@ -120,6 +162,21 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     previousOptions.current = options;
   }, [options, optionComparer, dispatch]);
 
+  const {
+    notifySelectionChanged,
+    notifyHighlightChanged,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+  } = useListChangeNotifiers<TOption>();
+
+  React.useEffect(() => {
+    notifySelectionChanged(selectedValue);
+  }, [selectedValue, notifySelectionChanged]);
+
+  React.useEffect(() => {
+    notifyHighlightChanged(highlightedValue);
+  }, [highlightedValue, notifyHighlightChanged]);
+
   const setSelectedValue = React.useCallback(
     (values: TOption[]) => {
       dispatch({
@@ -187,7 +244,13 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
         return;
       }
 
-      const keysToPreventDefault = ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'];
+      const keysToPreventDefault = ['Home', 'End', 'PageUp', 'PageDown'];
+
+      if (orientation === 'vertical') {
+        keysToPreventDefault.push('ArrowUp', 'ArrowDown');
+      } else {
+        keysToPreventDefault.push('ArrowLeft', 'ArrowRight');
+      }
 
       if (focusManagement === 'activeDescendant') {
         // When the child element is focused using the activeDescendant attribute,
@@ -217,8 +280,8 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
         return;
       }
 
-      if (listboxRef.current?.contains(document.activeElement)) {
-        // focus is within the listbox
+      if (listboxRef.current?.contains(event.relatedTarget)) {
+        // focus remains within the listbox
         return;
       }
 
@@ -266,12 +329,37 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     [options, isOptionDisabled, optionComparer, latestSelectedValue, latestHighlightedIndex],
   );
 
+  const firstFocusableOption = React.useMemo(() => {
+    if (focusManagement === 'activeDescendant') {
+      // options are not focusable when using activeDescendant
+      return undefined;
+    }
+
+    if (disabledItemsFocusable) {
+      return options[0];
+    }
+
+    for (let i = 0; i < options.length; i += 1) {
+      const option = options[i];
+      const optionState = getOptionState(option);
+      if (!optionState.disabled) {
+        return option;
+      }
+    }
+
+    return undefined;
+  }, [options, disabledItemsFocusable, getOptionState, focusManagement]);
+
   const getOptionTabIndex = React.useCallback(
-    (optionState: OptionState) => {
+    (option: TOption, optionState: OptionState) => {
       if (focusManagement === 'activeDescendant') {
         return undefined;
       }
 
+      if (latestHighlightedValue.current == null) {
+        return option === firstFocusableOption ? 0 : -1;
+      }
+
       if (!optionState.highlighted) {
         return -1;
       }
@@ -282,7 +370,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
       return 0;
     },
-    [focusManagement, disabledItemsFocusable],
+    [focusManagement, disabledItemsFocusable, firstFocusableOption, latestHighlightedValue],
   );
 
   const getOptionProps = React.useCallback(
@@ -300,7 +388,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
         onClick: createHandleOptionClick(option, otherHandlers),
         onPointerOver: createHandleOptionPointerOver(option, otherHandlers),
         role: 'option',
-        tabIndex: getOptionTabIndex(optionState),
+        tabIndex: getOptionTabIndex(option, optionState),
       };
     },
     [
@@ -312,6 +400,23 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     ],
   );
 
+  const contextValue: ListContextValue<TOption> = React.useMemo(
+    () => ({
+      getItemProps: getOptionProps,
+      getItemState: getOptionState,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+      focusManagement,
+    }),
+    [
+      getOptionProps,
+      getOptionState,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+      focusManagement,
+    ],
+  );
+
   React.useDebugValue({
     highlightedOption: highlightedValue,
     selectedOption: selectedValue,
@@ -325,5 +430,77 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     selectedOption: selectedValue,
     setSelectedValue,
     setHighlightedValue,
+    contextValue,
+  };
+}
+
+export interface UseListItemParameters<Item> {
+  item: Item;
+  ref?: React.Ref<HTMLElement>;
+}
+
+export function useListItem<Item>(parameters: UseListItemParameters<Item>) {
+  const { item, ref: externalRef } = parameters;
+
+  const itemRef = React.useRef<HTMLElement>(null);
+  const handleRef = useForkRef(itemRef, externalRef);
+
+  const listContext = React.useContext(ListContext);
+  if (!listContext) {
+    throw new Error('useListItem must be used within a ListProvider');
+  }
+
+  const {
+    getItemProps,
+    getItemState,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+  } = listContext;
+
+  const itemState = getItemState(item);
+  const { highlighted, selected } = itemState;
+
+  const rerender = useForcedRerendering();
+
+  React.useEffect(() => {
+    function updateHighlightedState(highlightedItem: Item | null) {
+      if (highlightedItem === item && !highlighted) {
+        rerender();
+      } else if (highlightedItem !== item && highlighted) {
+        rerender();
+      }
+    }
+
+    return registerHighlightChangeHandler(updateHighlightedState);
+  });
+
+  React.useEffect(() => {
+    function updateSelectedState(selectedItems: Item | Item[] | null) {
+      if (!selected) {
+        if (Array.isArray(selectedItems)) {
+          if (selectedItems.includes(item)) {
+            rerender();
+          }
+        } else if (selectedItems === item) {
+          rerender();
+        }
+      } else if (Array.isArray(selectedItems)) {
+        if (!selectedItems.includes(item)) {
+          rerender();
+        }
+      } else if (selectedItems !== item) {
+        rerender();
+      }
+    }
+
+    return registerSelectionChangeHandler(updateSelectedState);
+  }, [registerSelectionChangeHandler, rerender, selected, item]);
+
+  return {
+    getItemProps: <TOther extends EventHandlers = {}>(otherHandlers?: TOther) => ({
+      ...getItemProps(item, otherHandlers),
+      ref: handleRef,
+    }),
+    getItemState: () => getItemState(item),
   };
 }
diff --git a/packages/mui-base/src/useListbox/useListbox.types.ts b/packages/mui-base/src/useListbox/useListbox.types.ts
index 592889961cba40..b339e54375b628 100644
--- a/packages/mui-base/src/useListbox/useListbox.types.ts
+++ b/packages/mui-base/src/useListbox/useListbox.types.ts
@@ -5,6 +5,7 @@ type UseListboxStrictParametersRequiredKeys =
   | 'disableListWrap'
   | 'disabledItemsFocusable'
   | 'optionComparer'
+  | 'orientation'
   | 'optionStringifier'
   | 'selectionLimit';
 
@@ -124,6 +125,12 @@ export interface UseListboxParameters<TOption> {
    */
   disableListWrap?: boolean;
   focusManagement?: FocusManagementType;
+  /**
+   * A function that returns the DOM element associated with an option.
+   *
+   * @param option Option to get the DOM element for.
+   */
+  getOptionElement?: (option: TOption) => HTMLElement | null;
   /**
    * Id attribute of the listbox.
    */
@@ -143,6 +150,7 @@ export interface UseListboxParameters<TOption> {
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
     value: TOption[],
+    reason: ActionTypes,
   ) => void;
   /**
    * Callback fired when the highlighted option changes.
@@ -150,6 +158,7 @@ export interface UseListboxParameters<TOption> {
   onHighlightChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
     option: TOption | null,
+    reason: ActionTypes,
   ) => void;
   /**
    * A function that tests equality between two options.
@@ -169,6 +178,11 @@ export interface UseListboxParameters<TOption> {
    * Array of options to be rendered in the list.
    */
   options: TOption[];
+  /**
+   * Orientation of the items in the listbox.
+   * Determines the actions that are performed when arrow keys are pressed.
+   */
+  orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
   /**
    * Maximum number of options that can be selected at once.
    * Set to `null` to disable the limit.
diff --git a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts b/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts
index 426c7e1910a71e..5c717d80aafb3c 100644
--- a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts
+++ b/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import useMessageBus from '../utils/useMessageBus';
 
-const SELECTION_CHANGE_TOPIC = 'select:change-selection';
-const HIGHLIGHT_CHANGE_TOPIC = 'select:change-highlight';
+const SELECTION_CHANGE_TOPIC = Symbol('select:change-selection');
+const HIGHLIGHT_CHANGE_TOPIC = Symbol('select:change-highlight');
 
 export interface SelectChangeNotifiers<TValue> {
   /**
diff --git a/packages/mui-base/src/utils/useMessageBus.ts b/packages/mui-base/src/utils/useMessageBus.ts
index ef2d8d9f898c4b..79354a49ceb70e 100644
--- a/packages/mui-base/src/utils/useMessageBus.ts
+++ b/packages/mui-base/src/utils/useMessageBus.ts
@@ -1,14 +1,14 @@
 import * as React from 'react';
 
 export interface MessageBus {
-  subscribe(topic: string, callback: Function): () => void;
-  publish(topic: string, ...args: unknown[]): void;
+  subscribe(topic: symbol, callback: Function): () => void;
+  publish(topic: symbol, ...args: unknown[]): void;
 }
 
 export function createMessageBus(): MessageBus {
-  const listeners = new Map<string, Set<Function>>();
+  const listeners = new Map<symbol, Set<Function>>();
 
-  function subscribe(topic: string, callback: Function) {
+  function subscribe(topic: symbol, callback: Function) {
     let topicListeners = listeners.get(topic);
     if (!topicListeners) {
       topicListeners = new Set([callback]);
@@ -25,7 +25,7 @@ export function createMessageBus(): MessageBus {
     };
   }
 
-  function publish(topic: string, ...args: unknown[]) {
+  function publish(topic: symbol, ...args: unknown[]) {
     const topicListeners = listeners.get(topic);
     if (topicListeners) {
       topicListeners.forEach((callback) => callback(...args));

From fac8a2b80625c44c30ece3a80c2d2b95763fdfb0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 1 Mar 2023 21:35:00 +0100
Subject: [PATCH 02/49] Redesign unstyled Tabs to work with context

---
 .../components/tabs/KeyboardNavigation.js     |  16 +-
 .../components/tabs/KeyboardNavigation.tsx    |  16 +-
 .../base/components/tabs/UnstyledTabsBasic.js |  14 +-
 .../components/tabs/UnstyledTabsBasic.tsx     |  14 +-
 .../tabs/UnstyledTabsBasic.tsx.preview        |  14 +-
 .../components/tabs/UnstyledTabsCustomized.js |  14 +-
 .../tabs/UnstyledTabsCustomized.tsx           |  14 +-
 .../tabs/UnstyledTabsCustomized.tsx.preview   |  14 +-
 .../tabs/UnstyledTabsIntroduction.js          |   6 +-
 .../tabs/UnstyledTabsIntroduction.tsx         |   6 +-
 .../tabs/UnstyledTabsIntroduction.tsx.preview |   6 +-
 docs/pages/experiments/base/tabs.tsx          | 177 +++++++++++
 .../src/TabUnstyled/TabUnstyled.spec.tsx      |  12 +-
 .../src/TabUnstyled/TabUnstyled.test.tsx      |  33 +-
 .../mui-base/src/TabUnstyled/TabUnstyled.tsx  |  15 +-
 .../src/TabUnstyled/TabUnstyled.types.ts      |   4 +-
 .../src/TabsListUnstyled/TabsListUnstyled.tsx |  13 +-
 .../mui-base/src/TabsUnstyled/TabsContext.ts  |  14 +-
 .../src/TabsUnstyled/TabsUnstyled.test.tsx    | 156 +++++-----
 .../src/TabsUnstyled/TabsUnstyled.tsx         |  11 +-
 .../src/TabsUnstyled/TabsUnstyled.types.ts    |   6 +-
 packages/mui-base/src/useButton/useButton.ts  |   1 +
 .../mui-base/src/useButton/useButton.types.ts |   4 +
 .../useListbox/defaultListboxReducer.test.ts  |   8 +-
 .../src/useListbox/defaultListboxReducer.ts   |   2 -
 .../useControllableReducer.test.tsx           |   4 +
 .../src/useListbox/useControllableReducer.ts  |   2 +-
 .../mui-base/src/useListbox/useListbox.ts     |  29 +-
 packages/mui-base/src/useSelect/useSelect.ts  |  15 +-
 packages/mui-base/src/useTab/useTab.ts        | 114 ++++---
 packages/mui-base/src/useTab/useTab.types.ts  |  60 ++--
 .../mui-base/src/useTabs/TabsProvider.tsx     |  59 ++++
 packages/mui-base/src/useTabs/index.ts        |   4 +
 packages/mui-base/src/useTabs/useTabs.ts      |  30 +-
 .../mui-base/src/useTabs/useTabs.types.ts     |  13 +-
 .../src/useTabsList/TabsListProvider.tsx      |  66 ++++
 packages/mui-base/src/useTabsList/index.ts    |   3 +
 .../mui-base/src/useTabsList/useTabsList.ts   | 282 +++++++-----------
 .../src/useTabsList/useTabsList.types.ts      |  39 ++-
 .../mui-base/src/utils/useCompound.test.tsx   | 170 +++++++++++
 packages/mui-base/src/utils/useCompound.ts    | 119 ++++++++
 .../mui-base/src/utils/useMessageBus.test.ts  |  30 +-
 packages/mui-joy/src/TabList/TabList.tsx      |  16 +-
 packages/mui-joy/src/Tabs/Tabs.tsx            |   9 +-
 44 files changed, 1131 insertions(+), 523 deletions(-)
 create mode 100644 docs/pages/experiments/base/tabs.tsx
 create mode 100644 packages/mui-base/src/useTabs/TabsProvider.tsx
 create mode 100644 packages/mui-base/src/useTabsList/TabsListProvider.tsx
 create mode 100644 packages/mui-base/src/utils/useCompound.test.tsx
 create mode 100644 packages/mui-base/src/utils/useCompound.ts

diff --git a/docs/data/base/components/tabs/KeyboardNavigation.js b/docs/data/base/components/tabs/KeyboardNavigation.js
index 8b8bd17146f86c..57b80cd3c336e3 100644
--- a/docs/data/base/components/tabs/KeyboardNavigation.js
+++ b/docs/data/base/components/tabs/KeyboardNavigation.js
@@ -85,26 +85,26 @@ export default function AccessibleTabs1() {
     <div>
       <p>Selection following focus:</p>
       <TabsUnstyled
-        defaultValue={0}
+        defaultValue={1}
         aria-label="Tabs where selection follows focus"
         selectionFollowsFocus
       >
         <TabsList>
-          <Tab>One</Tab>
-          <Tab>Two</Tab>
-          <Tab>Three</Tab>
+          <Tab value={1}>One</Tab>
+          <Tab value={2}>Two</Tab>
+          <Tab value={3}>Three</Tab>
         </TabsList>
       </TabsUnstyled>
 
       <p>Selection independent of focus (default behavior):</p>
       <TabsUnstyled
-        defaultValue={0}
+        defaultValue={1}
         aria-label="Tabs where selection does not follow focus"
       >
         <TabsList>
-          <Tab>One</Tab>
-          <Tab>Two</Tab>
-          <Tab>Three</Tab>
+          <Tab value={1}>One</Tab>
+          <Tab value={2}>Two</Tab>
+          <Tab value={3}>Three</Tab>
         </TabsList>
       </TabsUnstyled>
     </div>
diff --git a/docs/data/base/components/tabs/KeyboardNavigation.tsx b/docs/data/base/components/tabs/KeyboardNavigation.tsx
index 8b8bd17146f86c..57b80cd3c336e3 100644
--- a/docs/data/base/components/tabs/KeyboardNavigation.tsx
+++ b/docs/data/base/components/tabs/KeyboardNavigation.tsx
@@ -85,26 +85,26 @@ export default function AccessibleTabs1() {
     <div>
       <p>Selection following focus:</p>
       <TabsUnstyled
-        defaultValue={0}
+        defaultValue={1}
         aria-label="Tabs where selection follows focus"
         selectionFollowsFocus
       >
         <TabsList>
-          <Tab>One</Tab>
-          <Tab>Two</Tab>
-          <Tab>Three</Tab>
+          <Tab value={1}>One</Tab>
+          <Tab value={2}>Two</Tab>
+          <Tab value={3}>Three</Tab>
         </TabsList>
       </TabsUnstyled>
 
       <p>Selection independent of focus (default behavior):</p>
       <TabsUnstyled
-        defaultValue={0}
+        defaultValue={1}
         aria-label="Tabs where selection does not follow focus"
       >
         <TabsList>
-          <Tab>One</Tab>
-          <Tab>Two</Tab>
-          <Tab>Three</Tab>
+          <Tab value={1}>One</Tab>
+          <Tab value={2}>Two</Tab>
+          <Tab value={3}>Three</Tab>
         </TabsList>
       </TabsUnstyled>
     </div>
diff --git a/docs/data/base/components/tabs/UnstyledTabsBasic.js b/docs/data/base/components/tabs/UnstyledTabsBasic.js
index c4112192089bb4..1ce19b7e447df7 100644
--- a/docs/data/base/components/tabs/UnstyledTabsBasic.js
+++ b/docs/data/base/components/tabs/UnstyledTabsBasic.js
@@ -6,15 +6,15 @@ import TabUnstyled from '@mui/base/TabUnstyled';
 
 export default function UnstyledTabsBasic() {
   return (
-    <TabsUnstyled defaultValue={0}>
+    <TabsUnstyled defaultValue={1}>
       <TabsListUnstyled>
-        <TabUnstyled>One</TabUnstyled>
-        <TabUnstyled>Two</TabUnstyled>
-        <TabUnstyled>Three</TabUnstyled>
+        <TabUnstyled value={1}>One</TabUnstyled>
+        <TabUnstyled value={2}>Two</TabUnstyled>
+        <TabUnstyled value={3}>Three</TabUnstyled>
       </TabsListUnstyled>
-      <TabPanelUnstyled value={0}>First page</TabPanelUnstyled>
-      <TabPanelUnstyled value={1}>Second page</TabPanelUnstyled>
-      <TabPanelUnstyled value={2}>Third page</TabPanelUnstyled>
+      <TabPanelUnstyled value={1}>First page</TabPanelUnstyled>
+      <TabPanelUnstyled value={2}>Second page</TabPanelUnstyled>
+      <TabPanelUnstyled value={3}>Third page</TabPanelUnstyled>
     </TabsUnstyled>
   );
 }
diff --git a/docs/data/base/components/tabs/UnstyledTabsBasic.tsx b/docs/data/base/components/tabs/UnstyledTabsBasic.tsx
index c4112192089bb4..1ce19b7e447df7 100644
--- a/docs/data/base/components/tabs/UnstyledTabsBasic.tsx
+++ b/docs/data/base/components/tabs/UnstyledTabsBasic.tsx
@@ -6,15 +6,15 @@ import TabUnstyled from '@mui/base/TabUnstyled';
 
 export default function UnstyledTabsBasic() {
   return (
-    <TabsUnstyled defaultValue={0}>
+    <TabsUnstyled defaultValue={1}>
       <TabsListUnstyled>
-        <TabUnstyled>One</TabUnstyled>
-        <TabUnstyled>Two</TabUnstyled>
-        <TabUnstyled>Three</TabUnstyled>
+        <TabUnstyled value={1}>One</TabUnstyled>
+        <TabUnstyled value={2}>Two</TabUnstyled>
+        <TabUnstyled value={3}>Three</TabUnstyled>
       </TabsListUnstyled>
-      <TabPanelUnstyled value={0}>First page</TabPanelUnstyled>
-      <TabPanelUnstyled value={1}>Second page</TabPanelUnstyled>
-      <TabPanelUnstyled value={2}>Third page</TabPanelUnstyled>
+      <TabPanelUnstyled value={1}>First page</TabPanelUnstyled>
+      <TabPanelUnstyled value={2}>Second page</TabPanelUnstyled>
+      <TabPanelUnstyled value={3}>Third page</TabPanelUnstyled>
     </TabsUnstyled>
   );
 }
diff --git a/docs/data/base/components/tabs/UnstyledTabsBasic.tsx.preview b/docs/data/base/components/tabs/UnstyledTabsBasic.tsx.preview
index 2669f0b1113b07..077b7ae06663d1 100644
--- a/docs/data/base/components/tabs/UnstyledTabsBasic.tsx.preview
+++ b/docs/data/base/components/tabs/UnstyledTabsBasic.tsx.preview
@@ -1,10 +1,10 @@
-<TabsUnstyled defaultValue={0}>
+<TabsUnstyled defaultValue={1}>
   <TabsListUnstyled>
-    <TabUnstyled>One</TabUnstyled>
-    <TabUnstyled>Two</TabUnstyled>
-    <TabUnstyled>Three</TabUnstyled>
+    <TabUnstyled value={1}>One</TabUnstyled>
+    <TabUnstyled value={2}>Two</TabUnstyled>
+    <TabUnstyled value={3}>Three</TabUnstyled>
   </TabsListUnstyled>
-  <TabPanelUnstyled value={0}>First page</TabPanelUnstyled>
-  <TabPanelUnstyled value={1}>Second page</TabPanelUnstyled>
-  <TabPanelUnstyled value={2}>Third page</TabPanelUnstyled>
+  <TabPanelUnstyled value={1}>First page</TabPanelUnstyled>
+  <TabPanelUnstyled value={2}>Second page</TabPanelUnstyled>
+  <TabPanelUnstyled value={3}>Third page</TabPanelUnstyled>
 </TabsUnstyled>
\ No newline at end of file
diff --git a/docs/data/base/components/tabs/UnstyledTabsCustomized.js b/docs/data/base/components/tabs/UnstyledTabsCustomized.js
index 1deefa2056b9e9..d7c9220c3b0f43 100644
--- a/docs/data/base/components/tabs/UnstyledTabsCustomized.js
+++ b/docs/data/base/components/tabs/UnstyledTabsCustomized.js
@@ -89,15 +89,15 @@ const TabsList = styled(TabsListUnstyled)(
 
 export default function UnstyledTabsCustomized() {
   return (
-    <TabsUnstyled defaultValue={0}>
+    <TabsUnstyled defaultValue={1}>
       <TabsList>
-        <Tab>One</Tab>
-        <Tab>Two</Tab>
-        <Tab>Three</Tab>
+        <Tab value={1}>One</Tab>
+        <Tab value={2}>Two</Tab>
+        <Tab value={3}>Three</Tab>
       </TabsList>
-      <TabPanel value={0}>First page</TabPanel>
-      <TabPanel value={1}>Second page</TabPanel>
-      <TabPanel value={2}>Third page</TabPanel>
+      <TabPanel value={1}>First page</TabPanel>
+      <TabPanel value={2}>Second page</TabPanel>
+      <TabPanel value={3}>Third page</TabPanel>
     </TabsUnstyled>
   );
 }
diff --git a/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx b/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx
index 1deefa2056b9e9..d7c9220c3b0f43 100644
--- a/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx
+++ b/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx
@@ -89,15 +89,15 @@ const TabsList = styled(TabsListUnstyled)(
 
 export default function UnstyledTabsCustomized() {
   return (
-    <TabsUnstyled defaultValue={0}>
+    <TabsUnstyled defaultValue={1}>
       <TabsList>
-        <Tab>One</Tab>
-        <Tab>Two</Tab>
-        <Tab>Three</Tab>
+        <Tab value={1}>One</Tab>
+        <Tab value={2}>Two</Tab>
+        <Tab value={3}>Three</Tab>
       </TabsList>
-      <TabPanel value={0}>First page</TabPanel>
-      <TabPanel value={1}>Second page</TabPanel>
-      <TabPanel value={2}>Third page</TabPanel>
+      <TabPanel value={1}>First page</TabPanel>
+      <TabPanel value={2}>Second page</TabPanel>
+      <TabPanel value={3}>Third page</TabPanel>
     </TabsUnstyled>
   );
 }
diff --git a/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx.preview b/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx.preview
index 481df4cdd1f6de..76364ff1a19211 100644
--- a/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx.preview
+++ b/docs/data/base/components/tabs/UnstyledTabsCustomized.tsx.preview
@@ -1,10 +1,10 @@
-<TabsUnstyled defaultValue={0}>
+<TabsUnstyled defaultValue={1}>
   <TabsList>
-    <Tab>One</Tab>
-    <Tab>Two</Tab>
-    <Tab>Three</Tab>
+    <Tab value={1}>One</Tab>
+    <Tab value={2}>Two</Tab>
+    <Tab value={3}>Three</Tab>
   </TabsList>
-  <TabPanel value={0}>First page</TabPanel>
-  <TabPanel value={1}>Second page</TabPanel>
-  <TabPanel value={2}>Third page</TabPanel>
+  <TabPanel value={1}>First page</TabPanel>
+  <TabPanel value={2}>Second page</TabPanel>
+  <TabPanel value={3}>Third page</TabPanel>
 </TabsUnstyled>
\ No newline at end of file
diff --git a/docs/data/base/components/tabs/UnstyledTabsIntroduction.js b/docs/data/base/components/tabs/UnstyledTabsIntroduction.js
index 97b2193bc1816a..6f8c6345249b89 100644
--- a/docs/data/base/components/tabs/UnstyledTabsIntroduction.js
+++ b/docs/data/base/components/tabs/UnstyledTabsIntroduction.js
@@ -98,9 +98,9 @@ export default function UnstyledTabsIntroduction() {
   return (
     <TabsUnstyled defaultValue={0}>
       <TabsList>
-        <Tab>My account</Tab>
-        <Tab>Profile</Tab>
-        <Tab>Language</Tab>
+        <Tab value={0}>My account</Tab>
+        <Tab value={1}>Profile</Tab>
+        <Tab value={2}>Language</Tab>
       </TabsList>
       <TabPanel value={0}>My account page</TabPanel>
       <TabPanel value={1}>Profile page</TabPanel>
diff --git a/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx b/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx
index 97b2193bc1816a..6f8c6345249b89 100644
--- a/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx
+++ b/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx
@@ -98,9 +98,9 @@ export default function UnstyledTabsIntroduction() {
   return (
     <TabsUnstyled defaultValue={0}>
       <TabsList>
-        <Tab>My account</Tab>
-        <Tab>Profile</Tab>
-        <Tab>Language</Tab>
+        <Tab value={0}>My account</Tab>
+        <Tab value={1}>Profile</Tab>
+        <Tab value={2}>Language</Tab>
       </TabsList>
       <TabPanel value={0}>My account page</TabPanel>
       <TabPanel value={1}>Profile page</TabPanel>
diff --git a/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx.preview b/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx.preview
index 480f510d20466d..c0e474e9b741ba 100644
--- a/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx.preview
+++ b/docs/data/base/components/tabs/UnstyledTabsIntroduction.tsx.preview
@@ -1,8 +1,8 @@
 <TabsUnstyled defaultValue={0}>
   <TabsList>
-    <Tab>My account</Tab>
-    <Tab>Profile</Tab>
-    <Tab>Language</Tab>
+    <Tab value={0}>My account</Tab>
+    <Tab value={1}>Profile</Tab>
+    <Tab value={2}>Language</Tab>
   </TabsList>
   <TabPanel value={0}>My account page</TabPanel>
   <TabPanel value={1}>Profile page</TabPanel>
diff --git a/docs/pages/experiments/base/tabs.tsx b/docs/pages/experiments/base/tabs.tsx
new file mode 100644
index 00000000000000..3775f432fbf1aa
--- /dev/null
+++ b/docs/pages/experiments/base/tabs.tsx
@@ -0,0 +1,177 @@
+import * as React from 'react';
+import { styled } from '@mui/system';
+import TabsUnstyled from '@mui/base/TabsUnstyled';
+import TabsListUnstyled from '@mui/base/TabsListUnstyled';
+import TabPanelUnstyled from '@mui/base/TabPanelUnstyled';
+import TabUnstyled, { tabUnstyledClasses } from '@mui/base/TabUnstyled';
+
+const blue = {
+  50: '#F0F7FF',
+  100: '#C2E0FF',
+  200: '#80BFFF',
+  300: '#66B2FF',
+  400: '#3399FF',
+  500: '#007FFF',
+  600: '#0072E5',
+  700: '#0059B2',
+  800: '#004C99',
+  900: '#003A75',
+};
+
+const grey = {
+  50: '#f6f8fa',
+  100: '#eaeef2',
+  200: '#d0d7de',
+  300: '#afb8c1',
+  400: '#8c959f',
+  500: '#6e7781',
+  600: '#57606a',
+  700: '#424a53',
+  800: '#32383f',
+  900: '#24292f',
+};
+
+const Tab = styled(TabUnstyled)`
+  font-family: IBM Plex Sans, sans-serif;
+  color: #fff;
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-weight: 600;
+  background-color: transparent;
+  width: 100%;
+  padding: 10px 12px;
+  margin: 6px 6px;
+  border: none;
+  border-radius: 7px;
+  display: flex;
+  justify-content: center;
+
+  &:hover {
+    background-color: ${blue[400]};
+  }
+
+  &:focus {
+    color: #fff;
+    outline: 3px solid ${blue[200]};
+  }
+
+  &.${tabUnstyledClasses.selected} {
+    background-color: #fff;
+    color: ${blue[600]};
+  }
+
+  &.${tabUnstyledClasses.disabled} {
+    opacity: 0.5;
+  }
+`;
+
+const TabPanel = styled(TabPanelUnstyled)(
+  ({ theme }) => `
+  width: 100%;
+  font-family: IBM Plex Sans, sans-serif;
+  font-size: 0.875rem;
+  padding: 20px 12px;
+  background: ${theme.palette.mode === 'dark' ? grey[900] : '#fff'};
+  border: 1px solid ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
+  border-radius: 12px;
+  box-sizing: border-box;
+  margin-bottom: 16px;
+  `,
+);
+
+const TabsList = styled(TabsListUnstyled)(
+  ({ theme }) => `
+  min-width: 400px;
+  background-color: ${blue[500]};
+  border-radius: 12px;
+  margin-bottom: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  align-content: space-between;
+  box-shadow: 0px 4px 30px ${theme.palette.mode === 'dark' ? grey[900] : grey[200]};
+  `,
+);
+
+function MoreTabs() {
+  return (
+    <React.Fragment>
+      <Tab value="settings">Settings</Tab>
+      <Tab disabled value="notifications">
+        Notifications
+      </Tab>
+      <Tab value="nested">Nested tabs</Tab>
+    </React.Fragment>
+  );
+}
+
+function MoreTabPanels() {
+  return (
+    <React.Fragment>
+      <TabPanel value="settings">Settings page</TabPanel>
+      <TabPanel value="notifications">Notifications page</TabPanel>
+      <TabPanel value="nested">
+        <TabsUnstyled defaultValue="my-account">
+          <TabsList>
+            <Tab value="my-account">My account</Tab>
+            <Tab value="profile">Profile</Tab>
+            <Tab value="language">Language</Tab>
+            <MoreTabs />
+          </TabsList>
+          <TabPanel value="my-account">My account page</TabPanel>
+          <TabPanel value="profile">Profile page</TabPanel>
+          <TabPanel value="language">Language page</TabPanel>
+          <MoreTabPanels />
+        </TabsUnstyled>
+      </TabPanel>
+    </React.Fragment>
+  );
+}
+
+export default function UnstyledTabsIntroduction() {
+  const [selectionFollowsFocus, setSelectionFollowsFocus] = React.useState(false);
+  const [selectedTab, setSelectedTab] = React.useState<string | number>('profile');
+
+  const handleTabChange = (
+    event: React.SyntheticEvent | null,
+    newValue: string | number | null,
+  ) => {
+    setSelectedTab(newValue!);
+  };
+
+  return (
+    <React.Fragment>
+      <label>
+        <input
+          type="checkbox"
+          checked={selectionFollowsFocus}
+          onChange={(e) => setSelectionFollowsFocus(e.target.checked)}
+        />{' '}
+        Selection follows focus
+      </label>
+      <TabsUnstyled
+        value={selectedTab}
+        onChange={handleTabChange}
+        selectionFollowsFocus={selectionFollowsFocus}
+      >
+        <TabsList>
+          <Tab value="my-account">My account</Tab>
+          <Tab value="profile">Profile</Tab>
+          <Tab value="language">Language</Tab>
+          <MoreTabs />
+        </TabsList>
+        <TabPanel value="my-account">My account page</TabPanel>
+        <TabPanel value="profile">Profile page</TabPanel>
+        <TabPanel value="language">Language page</TabPanel>
+        <MoreTabPanels />
+
+        <TabsList>
+          <Tab value="my-account">My account</Tab>
+          <Tab value="profile">Profile</Tab>
+          <Tab value="language">Language</Tab>
+          <MoreTabs />
+        </TabsList>
+      </TabsUnstyled>
+    </React.Fragment>
+  );
+}
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.spec.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.spec.tsx
index a093230a9ac0c6..5829f1163a27cc 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.spec.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.spec.tsx
@@ -7,7 +7,7 @@ function Root(props: TabUnstyledRootSlotProps) {
   return <div data-active={ownerState.active} {...other} />;
 }
 
-const styledTab = <TabUnstyled slots={{ root: Root }} />;
+const styledTab = <TabUnstyled value={0} slots={{ root: Root }} />;
 
 const polymorphicComponentTest = () => {
   const CustomComponent: React.FC<{ stringProp: string; numberProp: number }> =
@@ -18,20 +18,22 @@ const polymorphicComponentTest = () => {
   return (
     <div>
       {/* @ts-expect-error */}
-      <TabUnstyled invalidProp={0} />
+      <TabUnstyled value={0} invalidProp={0} />
 
-      <TabUnstyled component="a" href="#" />
+      <TabUnstyled value={0} component="a" href="#" />
 
-      <TabUnstyled component={CustomComponent} stringProp="test" numberProp={0} />
+      <TabUnstyled value={0} component={CustomComponent} stringProp="test" numberProp={0} />
       {/* @ts-expect-error */}
-      <TabUnstyled component={CustomComponent} />
+      <TabUnstyled value={0} component={CustomComponent} />
 
       <TabUnstyled
+        value={0}
         component="button"
         onClick={(e: React.MouseEvent<HTMLButtonElement>) => e.currentTarget.checkValidity()}
       />
 
       <TabUnstyled<'button'>
+        value={0}
         component="button"
         ref={(elem) => {
           expectType<HTMLButtonElement | null, typeof elem>(elem);
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
index 74c8c497f8c192..d5c7c3958eb152 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
@@ -1,18 +1,41 @@
 import * as React from 'react';
 import { createMount, createRenderer, describeConformanceUnstyled } from 'test/utils';
 import TabUnstyled, { tabUnstyledClasses } from '@mui/base/TabUnstyled';
-import { TabsContext } from '@mui/base/TabsUnstyled';
+import { TabsListProvider, TabsListProviderValue } from '../useTabsList';
+import { TabsContext } from '../TabsUnstyled';
 
 describe('<TabUnstyled />', () => {
   const mount = createMount();
   const { render } = createRenderer();
 
+  const testTabsListContext: TabsListProviderValue = {
+    registerItem: () => {},
+    unregisterItem: () => {},
+    getItemIndex: () => 0,
+    totalSubitemCount: 1,
+    getItemProps() {
+      return {
+        'aria-disabled': undefined,
+        'aria-selected': undefined,
+        onClick: () => {},
+        onPointerOver: () => {},
+        role: 'tab' as const,
+      } as any;
+    },
+    getItemState() {
+      return { disabled: false, highlighted: false, selected: false, index: 0 };
+    },
+    registerHighlightChangeHandler: () => () => {},
+    registerSelectionChangeHandler: () => () => {},
+    focusManagement: 'DOM',
+  };
+
   describeConformanceUnstyled(<TabUnstyled value="1" />, () => ({
     inheritComponent: 'div',
     render: (node) => {
       const { container, ...other } = render(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
-          {node}
+        <TabsContext.Provider value={{ idPrefix: '', value: 0, onSelected() {} }}>
+          <TabsListProvider value={testTabsListContext}>{node}</TabsListProvider>
         </TabsContext.Provider>,
       );
 
@@ -20,8 +43,8 @@ describe('<TabUnstyled />', () => {
     },
     mount: (node: any) => {
       const wrapper = mount(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
-          {node}
+        <TabsContext.Provider value={{ idPrefix: '', value: 0, onSelected() {} }}>
+          <TabsListProvider value={testTabsListContext}>{node}</TabsListProvider>
         </TabsContext.Provider>,
       );
       return wrapper.childAt(0);
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
index 283b189989efb9..cf44579186671c 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
@@ -51,27 +51,16 @@ const TabUnstyled = React.forwardRef<unknown, TabUnstyledProps>(function TabUnst
   const tabRef = React.useRef<HTMLButtonElement | HTMLAnchorElement | HTMLElement>();
   const handleRef = useForkRef(tabRef, ref);
 
-  const { active, focusVisible, setFocusVisible, selected, getRootProps } = useTab({
+  const { active, highlighted, selected, getRootProps } = useTab({
     ...props,
     ref: handleRef,
   });
 
-  React.useImperativeHandle(
-    action,
-    () => ({
-      focusVisible: () => {
-        setFocusVisible(true);
-        tabRef.current!.focus();
-      },
-    }),
-    [setFocusVisible],
-  );
-
   const ownerState = {
     ...props,
     active,
-    focusVisible,
     disabled,
+    highlighted,
     selected,
   };
 
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts b/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
index 50c0e7a7238c74..51b4f3f85a501f 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
@@ -11,7 +11,7 @@ export interface TabUnstyledOwnProps
   /**
    * You can provide your own value. Otherwise, we fall back to the child position index.
    */
-  value?: number | string;
+  value: number | string;
   /**
    * Callback invoked when new value is being set.
    */
@@ -53,8 +53,8 @@ export interface TabUnstyledTypeMap<P = {}, D extends React.ElementType = 'butto
 
 export type TabUnstyledOwnerState = TabUnstyledProps & {
   active: boolean;
-  focusVisible: boolean;
   disabled: boolean;
+  highlighted: boolean;
   selected: boolean;
 };
 
diff --git a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
index e9ac6199bfd266..cc6a2aee5c4b11 100644
--- a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
+++ b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
@@ -11,6 +11,7 @@ import {
 } from './TabsListUnstyled.types';
 import useTabsList from '../useTabsList';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
+import TabsListProvider from '../useTabsList/TabsListProvider';
 
 const useUtilityClasses = (ownerState: { orientation: 'horizontal' | 'vertical' }) => {
   const { orientation } = ownerState;
@@ -35,7 +36,9 @@ const useUtilityClasses = (ownerState: { orientation: 'horizontal' | 'vertical'
 const TabsListUnstyled = React.forwardRef<unknown, TabsListUnstyledProps>((props, ref) => {
   const { children, component, slotProps = {}, slots = {}, ...other } = props;
 
-  const { isRtl, orientation, getRootProps, processChildren } = useTabsList({ ...props, ref });
+  const { isRtl, orientation, getRootProps, contextValue } = useTabsList({
+    ref,
+  });
 
   const ownerState = {
     ...props,
@@ -55,9 +58,11 @@ const TabsListUnstyled = React.forwardRef<unknown, TabsListUnstyledProps>((props
     className: classes.root,
   });
 
-  const processedChildren = processChildren();
-
-  return <TabsListRoot {...tabsListRootProps}>{processedChildren}</TabsListRoot>;
+  return (
+    <TabsListProvider value={contextValue}>
+      <TabsListRoot {...tabsListRootProps}>{children}</TabsListRoot>
+    </TabsListProvider>
+  );
 }) as OverridableComponent<TabsListUnstyledTypeMap>;
 
 TabsListUnstyled.propTypes /* remove-proptypes */ = {
diff --git a/packages/mui-base/src/TabsUnstyled/TabsContext.ts b/packages/mui-base/src/TabsUnstyled/TabsContext.ts
index 1752319ef080fc..30ea4501ded99b 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsContext.ts
+++ b/packages/mui-base/src/TabsUnstyled/TabsContext.ts
@@ -8,11 +8,11 @@ export interface TabsContextValue {
   /**
    * The currently selected tab's value.
    */
-  value: number | string | false;
+  value: number | string | null;
   /**
    * Callback for setting new value.
    */
-  onSelected: (event: React.SyntheticEvent, value: number | string | false) => void;
+  onSelected: (event: React.SyntheticEvent | null, value: number | string | null) => void;
   /**
    * The component orientation (layout flow direction).
    */
@@ -37,11 +37,13 @@ if (process.env.NODE_ENV !== 'production') {
   Context.displayName = 'TabsContext';
 }
 
-/**
- * @returns {unknown}
- */
 export function useTabContext() {
-  return React.useContext(Context);
+  const context = React.useContext(Context);
+  if (context == null) {
+    throw new Error('No TabsContext provided');
+  }
+
+  return context;
 }
 
 export function getPanelId(context: TabsContextValue, value: number | string | false) {
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
index 282b974d1c5bd9..064b66924036cf 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
@@ -48,7 +48,7 @@ describe('<TabsUnstyled />', () => {
     render(
       <Tabs>
         <TabsList aria-label="string label">
-          <Tab />
+          <Tab value={0} />
         </TabsList>
       </Tabs>,
     );
@@ -62,7 +62,7 @@ describe('<TabsUnstyled />', () => {
         <h3 id="label-id">complex name</h3>
         <Tabs>
           <TabsList aria-labelledby="label-id">
-            <Tab />
+            <Tab value={0} />
           </TabsList>
         </Tabs>
       </React.Fragment>,
@@ -76,7 +76,9 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole } = render(
         <Tabs value={0}>
           {null}
-          <Tab />
+          <TabsList>
+            <Tab value={1} />
+          </TabsList>
         </Tabs>,
       );
       expect(getAllByRole('tab')).to.have.lengthOf(1);
@@ -90,8 +92,8 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole, setProps } = render(
         <Tabs value={1}>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
@@ -108,8 +110,8 @@ describe('<TabsUnstyled />', () => {
     const tabs = (
       <Tabs value={1}>
         <TabsList>
-          <Tab />
-          <Tab />
+          <Tab value={0} />
+          <Tab value={1} />
         </TabsList>
       </Tabs>
     );
@@ -128,8 +130,8 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole } = render(
         <Tabs value={0} onChange={handleChange}>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
@@ -144,8 +146,8 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole } = render(
         <Tabs value={0} onChange={handleChange}>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
@@ -159,17 +161,19 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole } = render(
         <Tabs value={0} onChange={handleChange} selectionFollowsFocus>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
-      const [, lastTab] = getAllByRole('tab');
+      const [firstTab] = getAllByRole('tab');
 
       act(() => {
-        lastTab.focus();
+        firstTab.focus();
       });
 
+      fireEvent.keyDown(firstTab, { key: 'ArrowRight' });
+
       expect(handleChange.callCount).to.equal(1);
       expect(handleChange.firstCall.args[1]).to.equal(1);
     });
@@ -179,8 +183,8 @@ describe('<TabsUnstyled />', () => {
       const { getAllByRole } = render(
         <Tabs value={0} onChange={handleChange} selectionFollowsFocus>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
@@ -239,12 +243,12 @@ describe('<TabsUnstyled />', () => {
                 onChange={handleChange}
                 onKeyDown={handleKeyDown}
                 orientation={orientation as TabsUnstyledProps['orientation']}
-                value={1}
+                value={0}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -274,9 +278,9 @@ describe('<TabsUnstyled />', () => {
                 value={0}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -306,9 +310,9 @@ describe('<TabsUnstyled />', () => {
                 value={1}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -338,9 +342,9 @@ describe('<TabsUnstyled />', () => {
                 value={1}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -366,12 +370,12 @@ describe('<TabsUnstyled />', () => {
                 onKeyDown={handleKeyDown}
                 orientation={orientation as TabsUnstyledProps['orientation']}
                 selectionFollowsFocus
-                value={1}
+                value={2}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab disabled />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} disabled />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -398,12 +402,12 @@ describe('<TabsUnstyled />', () => {
                 onChange={handleChange}
                 onKeyDown={handleKeyDown}
                 orientation={orientation as TabsUnstyledProps['orientation']}
-                value={1}
+                value={2}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -433,9 +437,9 @@ describe('<TabsUnstyled />', () => {
                 value={2}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -465,9 +469,9 @@ describe('<TabsUnstyled />', () => {
                 value={1}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -484,7 +488,7 @@ describe('<TabsUnstyled />', () => {
             expect(handleKeyDown.firstCall.args[0]).to.have.property('defaultPrevented', true);
           });
 
-          it('when `selectionFollowsFocus` moves focus to the next tab while activating it it', () => {
+          it('when `selectionFollowsFocus` moves focus to the next tab while activating it', () => {
             const handleChange = spy();
             const handleKeyDown = spy();
             const { getAllByRole } = render(
@@ -497,9 +501,9 @@ describe('<TabsUnstyled />', () => {
                 value={1}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -525,12 +529,12 @@ describe('<TabsUnstyled />', () => {
                 onKeyDown={handleKeyDown}
                 orientation={orientation as TabsUnstyledProps['orientation']}
                 selectionFollowsFocus
-                value={1}
+                value={0}
               >
                 <TabsList>
-                  <Tab />
-                  <Tab disabled />
-                  <Tab />
+                  <Tab value={0} />
+                  <Tab value={1} disabled />
+                  <Tab value={2} />
                 </TabsList>
               </Tabs>,
             );
@@ -555,11 +559,11 @@ describe('<TabsUnstyled />', () => {
           const handleChange = spy();
           const handleKeyDown = spy();
           const { getAllByRole } = render(
-            <Tabs onChange={handleChange} onKeyDown={handleKeyDown} value={1}>
+            <Tabs onChange={handleChange} onKeyDown={handleKeyDown} value={2}>
               <TabsList>
-                <Tab />
-                <Tab />
-                <Tab />
+                <Tab value={0} />
+                <Tab value={1} />
+                <Tab value={2} />
               </TabsList>
             </Tabs>,
           );
@@ -582,9 +586,9 @@ describe('<TabsUnstyled />', () => {
           const { getAllByRole } = render(
             <Tabs onChange={handleChange} onKeyDown={handleKeyDown} selectionFollowsFocus value={2}>
               <TabsList>
-                <Tab />
-                <Tab />
-                <Tab />
+                <Tab value={0} />
+                <Tab value={1} />
+                <Tab value={2} />
               </TabsList>
             </Tabs>,
           );
@@ -607,9 +611,9 @@ describe('<TabsUnstyled />', () => {
           const { getAllByRole } = render(
             <Tabs onKeyDown={handleKeyDown} selectionFollowsFocus value={2}>
               <TabsList>
-                <Tab disabled />
-                <Tab />
-                <Tab />
+                <Tab value={0} disabled />
+                <Tab value={1} />
+                <Tab value={2} />
               </TabsList>
             </Tabs>,
           );
@@ -631,11 +635,11 @@ describe('<TabsUnstyled />', () => {
           const handleChange = spy();
           const handleKeyDown = spy();
           const { getAllByRole } = render(
-            <Tabs onChange={handleChange} onKeyDown={handleKeyDown} value={1}>
+            <Tabs onChange={handleChange} onKeyDown={handleKeyDown} value={0}>
               <TabsList>
-                <Tab />
-                <Tab />
-                <Tab />
+                <Tab value={0} />
+                <Tab value={1} />
+                <Tab value={2} />
               </TabsList>
             </Tabs>,
           );
@@ -658,9 +662,9 @@ describe('<TabsUnstyled />', () => {
           const { getAllByRole } = render(
             <Tabs onChange={handleChange} onKeyDown={handleKeyDown} selectionFollowsFocus value={0}>
               <TabsList>
-                <Tab />
-                <Tab />
-                <Tab />
+                <Tab value={0} />
+                <Tab value={1} />
+                <Tab value={2} />
               </TabsList>
             </Tabs>,
           );
@@ -681,11 +685,11 @@ describe('<TabsUnstyled />', () => {
         it('moves focus to first non-disabled tab', () => {
           const handleKeyDown = spy();
           const { getAllByRole } = render(
-            <Tabs onKeyDown={handleKeyDown} selectionFollowsFocus value={2}>
+            <Tabs onKeyDown={handleKeyDown} selectionFollowsFocus value={0}>
               <TabsList>
-                <Tab />
-                <Tab />
-                <Tab disabled />
+                <Tab value={0} />
+                <Tab value={1} />
+                <Tab value={2} disabled />
               </TabsList>
             </Tabs>,
           );
@@ -705,10 +709,10 @@ describe('<TabsUnstyled />', () => {
 
     it('should allow to focus first tab when there are no active tabs', () => {
       const { getAllByRole } = render(
-        <Tabs value={false}>
+        <Tabs>
           <TabsList>
-            <Tab />
-            <Tab />
+            <Tab value={0} />
+            <Tab value={1} />
           </TabsList>
         </Tabs>,
       );
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
index 4791bbb4db9077..7888518e34cdd7 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
@@ -10,7 +10,7 @@ import {
   TabsUnstyledTypeMap,
 } from './TabsUnstyled.types';
 import useTabs from '../useTabs';
-import Context from './TabsContext';
+import TabsProvider from '../useTabs/TabsProvider';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
 
 const useUtilityClasses = (ownerState: { orientation: 'horizontal' | 'vertical' }) => {
@@ -33,7 +33,10 @@ const useUtilityClasses = (ownerState: { orientation: 'horizontal' | 'vertical'
  *
  * - [TabsUnstyled API](https://mui.com/base/react-tabs/components-api/#tabs-unstyled)
  */
-const TabsUnstyled = React.forwardRef<unknown, TabsUnstyledProps>((props, ref) => {
+const TabsUnstyled = React.forwardRef<unknown, TabsUnstyledProps>(function TabsUnstyled(
+  props,
+  ref,
+) {
   const {
     children,
     value: valueProp,
@@ -48,7 +51,7 @@ const TabsUnstyled = React.forwardRef<unknown, TabsUnstyledProps>((props, ref) =
     ...other
   } = props;
 
-  const { tabsContextValue } = useTabs(props);
+  const { contextValue } = useTabs(props);
 
   const ownerState = {
     ...props,
@@ -72,7 +75,7 @@ const TabsUnstyled = React.forwardRef<unknown, TabsUnstyledProps>((props, ref) =
 
   return (
     <TabsRoot {...tabsRootProps}>
-      <Context.Provider value={tabsContextValue}>{children}</Context.Provider>
+      <TabsProvider value={contextValue}>{children}</TabsProvider>
     </TabsRoot>
   );
 }) as OverridableComponent<TabsUnstyledTypeMap>;
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
index 9b094fe5378b69..140b5820cb6e39 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
@@ -17,11 +17,11 @@ export interface TabsUnstyledOwnProps {
    * The value of the currently selected `Tab`.
    * If you don't want any selected `Tab`, you can set this prop to `false`.
    */
-  value?: string | number | false;
+  value?: string | number | null;
   /**
    * The default value. Use when the component is not controlled.
    */
-  defaultValue?: string | number | false;
+  defaultValue?: string | number | null;
   /**
    * The component orientation (layout flow direction).
    * @default 'horizontal'
@@ -36,7 +36,7 @@ export interface TabsUnstyledOwnProps {
   /**
    * Callback invoked when new value is being set.
    */
-  onChange?: (event: React.SyntheticEvent, value: number | string | boolean) => void;
+  onChange?: (event: React.SyntheticEvent | null, value: number | string | null) => void;
   /**
    * If `true` the selected tab changes on focus. Otherwise it only
    * changes on activation.
diff --git a/packages/mui-base/src/useButton/useButton.ts b/packages/mui-base/src/useButton/useButton.ts
index a8e4907bfcdb14..588e1403fcf32a 100644
--- a/packages/mui-base/src/useButton/useButton.ts
+++ b/packages/mui-base/src/useButton/useButton.ts
@@ -235,5 +235,6 @@ export default function useButton(parameters: UseButtonParameters): UseButtonRet
     setFocusVisible,
     disabled,
     active,
+    ref: handleRef,
   };
 }
diff --git a/packages/mui-base/src/useButton/useButton.types.ts b/packages/mui-base/src/useButton/useButton.types.ts
index 77e5fcb0899eab..c492df913b7d64 100644
--- a/packages/mui-base/src/useButton/useButton.types.ts
+++ b/packages/mui-base/src/useButton/useButton.types.ts
@@ -69,4 +69,8 @@ export interface UseButtonReturnValue {
    * @default false
    */
   active: boolean;
+  /**
+   * A ref to the component's root element.
+   */
+  ref: ((instance: unknown) => void) | null;
 }
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
index 31b6021d81d139..6f2ccd7fe84b2f 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
@@ -5,7 +5,7 @@ import defaultReducer from './defaultListboxReducer';
 
 describe('useListbox defaultReducer', () => {
   describe('action: setControlledValue', () => {
-    it("assigns the provided value to the state's selectedValue", () => {
+    it("assigns the provided value to the state's selectedValues", () => {
       const state: ListboxState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
@@ -59,7 +59,7 @@ describe('useListbox defaultReducer', () => {
   });
 
   describe('action: optionClick', () => {
-    it('sets the selectedValue to the clicked value', () => {
+    it('sets the selectedValues to the clicked value', () => {
       const state: ListboxState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
@@ -85,7 +85,7 @@ describe('useListbox defaultReducer', () => {
       expect(result.selectedValues).to.deep.equal(['two']);
     });
 
-    it('replaces the selectedValue with the clicked value if selectionLimit = 1', () => {
+    it('replaces the selectedValues with the clicked value if selectionLimit = 1', () => {
       const state: ListboxState<string> = {
         highlightedValue: 'a',
         selectedValues: ['one'],
@@ -336,7 +336,7 @@ describe('useListbox defaultReducer', () => {
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
-      it('replaces the selectedValue with the highlighted value if selectionLimit = 1', () => {
+      it('replaces the selectedValues with the highlighted value if selectionLimit = 1', () => {
         const state: ListboxState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
index 13e64d318996b6..e24c16545b4b15 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
@@ -431,8 +431,6 @@ export default function defaultListboxReducer<TOption>(
 ): Readonly<ListboxState<TOption>> {
   const { type } = action;
 
-  console.log('reducer called', type, action);
-
   switch (type) {
     case ActionTypes.keyDown:
       return handleKeyDown(action.event, state, action.props);
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx b/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
index 8fd84a0b0aa74d..284ad01db37cc0 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
@@ -29,6 +29,7 @@ describe('useControllableReducer', () => {
         disabledItemsFocusable: false,
         optionComparer: (a, b) => a === b,
         optionStringifier: (option) => option,
+        orientation: 'vertical',
         selectionLimit: null,
       };
 
@@ -62,6 +63,7 @@ describe('useControllableReducer', () => {
         disabledItemsFocusable: false,
         optionComparer: (a, b) => a === b,
         optionStringifier: (option) => option,
+        orientation: 'vertical',
         selectionLimit: null,
       };
 
@@ -104,6 +106,7 @@ describe('useControllableReducer', () => {
           optionStringifier: (option) => option,
           onChange: handleChange,
           onHighlightChange: handleHighlightChange,
+          orientation: 'vertical',
           selectionLimit: null,
         };
 
@@ -145,6 +148,7 @@ describe('useControllableReducer', () => {
           optionStringifier: (option) => option,
           onChange: handleChange,
           onHighlightChange: handleHighlightChange,
+          orientation: 'vertical',
           selectionLimit: null,
         };
 
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.ts b/packages/mui-base/src/useListbox/useControllableReducer.ts
index 75fa1aa35123c6..29ae0f8b3ac9a3 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.ts
+++ b/packages/mui-base/src/useListbox/useControllableReducer.ts
@@ -18,7 +18,7 @@ function getControlledState<TOption>(
   props: UseListboxParametersWithDefaults<TOption>,
 ) {
   if (props.value !== undefined) {
-    return { ...internalState, selectedValue: props.value };
+    return { ...internalState, selectedValues: props.value };
   }
 
   return internalState;
diff --git a/packages/mui-base/src/useListbox/useListbox.ts b/packages/mui-base/src/useListbox/useListbox.ts
index 036a20594e5569..4a4570e28fdca8 100644
--- a/packages/mui-base/src/useListbox/useListbox.ts
+++ b/packages/mui-base/src/useListbox/useListbox.ts
@@ -34,6 +34,9 @@ export interface ListContextValue<Item> {
 }
 
 export const ListContext = React.createContext<ListContextValue<any> | null>(null);
+if (process.env.NODE_ENV !== 'production') {
+  ListContext.displayName = 'ListContext';
+}
 
 /**
  * @ignore - internal hook.
@@ -110,7 +113,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     [props],
   );
 
-  const [{ highlightedValue, selectedValues: selectedValue }, dispatch] = useControllableReducer(
+  const [{ highlightedValue, selectedValues }, dispatch] = useControllableReducer(
     defaultReducer,
     externalReducer,
     propsWithDefaults,
@@ -126,14 +129,14 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
   React.useEffect(() => {
     // if a controlled value changes, we need to update the state to keep things in sync
-    if (valueParam !== undefined && valueParam !== selectedValue) {
+    if (valueParam !== undefined && valueParam !== selectedValues) {
       dispatch({
         type: ActionTypes.setValue,
         event: null,
         value: valueParam,
       });
     }
-  }, [valueParam, selectedValue, dispatch]);
+  }, [valueParam, selectedValues, dispatch]);
 
   const highlightedIndex = React.useMemo(() => {
     return highlightedValue == null
@@ -142,7 +145,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   }, [highlightedValue, options, optionComparer]);
 
   // introducing refs to avoid recreating the getOptionState function on each change.
-  const latestSelectedValue = useLatest(selectedValue);
+  const latestSelectedValues = useLatest(selectedValues);
   const latestHighlightedIndex = useLatest(highlightedIndex);
   const latestHighlightedValue = useLatest(highlightedValue);
   const previousOptions = React.useRef<TOption[]>([]);
@@ -170,8 +173,8 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   } = useListChangeNotifiers<TOption>();
 
   React.useEffect(() => {
-    notifySelectionChanged(selectedValue);
-  }, [selectedValue, notifySelectionChanged]);
+    notifySelectionChanged(selectedValues);
+  }, [selectedValues, notifySelectionChanged]);
 
   React.useEffect(() => {
     notifyHighlightChanged(highlightedValue);
@@ -312,7 +315,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   const getOptionState = React.useCallback(
     (option: TOption): OptionState => {
       const index = options.findIndex((opt) => optionComparer(opt, option));
-      const selected = (latestSelectedValue.current ?? []).some(
+      const selected = (latestSelectedValues.current ?? []).some(
         (value) => value != null && optionComparer(option, value),
       );
 
@@ -326,7 +329,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
         selected,
       };
     },
-    [options, isOptionDisabled, optionComparer, latestSelectedValue, latestHighlightedIndex],
+    [options, isOptionDisabled, optionComparer, latestSelectedValues, latestHighlightedIndex],
   );
 
   const firstFocusableOption = React.useMemo(() => {
@@ -356,7 +359,8 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
         return undefined;
       }
 
-      if (latestHighlightedValue.current == null) {
+      // TODO: check if using highlightedValue instead of latestHighlightedValue.current does not kill performance
+      if (highlightedValue == null) {
         return option === firstFocusableOption ? 0 : -1;
       }
 
@@ -370,7 +374,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
       return 0;
     },
-    [focusManagement, disabledItemsFocusable, firstFocusableOption, latestHighlightedValue],
+    [focusManagement, disabledItemsFocusable, firstFocusableOption, highlightedValue],
   );
 
   const getOptionProps = React.useCallback(
@@ -419,7 +423,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
   React.useDebugValue({
     highlightedOption: highlightedValue,
-    selectedOption: selectedValue,
+    selectedOptions: selectedValues,
   });
 
   return {
@@ -427,7 +431,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     getOptionProps,
     getOptionState,
     highlightedOption: highlightedValue,
-    selectedOption: selectedValue,
+    selectedOptions: selectedValues,
     setSelectedValue,
     setHighlightedValue,
     contextValue,
@@ -502,5 +506,6 @@ export function useListItem<Item>(parameters: UseListItemParameters<Item>) {
       ref: handleRef,
     }),
     getItemState: () => getItemState(item),
+    ref: handleRef,
   };
 }
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 52afed2c737012..f0cc9b14dfe83d 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -282,12 +282,12 @@ function useSelect<TValue, Multiple extends boolean = false>(
     getOptionProps: getListboxOptionProps,
     getOptionState,
     highlightedOption,
-    selectedOption,
+    selectedOptions,
   } = useListbox(useListboxParameters);
 
   React.useEffect(() => {
-    notifySelectionChanged(selectedOption);
-  }, [selectedOption, notifySelectionChanged]);
+    notifySelectionChanged(selectedOptions);
+  }, [selectedOptions, notifySelectionChanged]);
 
   React.useEffect(() => {
     notifyHighlightChanged(highlightedOption);
@@ -333,7 +333,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
   );
 
   React.useDebugValue({
-    selectedOption,
+    selectedOptions,
     highlightedOption,
     open,
   });
@@ -363,7 +363,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
       getListboxProps,
       contextValue,
       open,
-      value: selectedOption as SelectValue<TValue, Multiple>,
+      value: selectedOptions as SelectValue<TValue, Multiple>,
       highlightedOption,
     };
   }
@@ -376,7 +376,10 @@ function useSelect<TValue, Multiple extends boolean = false>(
     getListboxProps,
     contextValue,
     open,
-    value: (selectedOption.length > 0 ? selectedOption[0] : null) as SelectValue<TValue, Multiple>,
+    value: (selectedOptions.length > 0 ? selectedOptions[0] : null) as SelectValue<
+      TValue,
+      Multiple
+    >,
     highlightedOption,
   };
 }
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index ca31046473d8d9..881301d8ec19d8 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -1,7 +1,12 @@
-import { useTabContext, getTabId, getPanelId } from '../TabsUnstyled';
-import useButton from '../useButton';
+import * as React from 'react';
+import { unstable_useId as useId, unstable_useForkRef as useForkRef } from '@mui/utils';
+import { useTabContext } from '../TabsUnstyled';
 import { UseTabParameters, UseTabReturnValue, UseTabRootSlotProps } from './useTab.types';
 import { EventHandlers } from '../utils';
+import { useCompoundItem } from '../utils/useCompound';
+import { useListItem } from '../useListbox';
+import useButton from '../useButton';
+import { TabMetadata } from '../useTabs';
 /**
  *
  * Demos:
@@ -13,85 +18,74 @@ import { EventHandlers } from '../utils';
  * - [useTab API](https://mui.com/base/react-tabs/hooks-api/#use-tab)
  */
 function useTab(parameters: UseTabParameters): UseTabReturnValue {
-  const { value: valueProp, onChange, onClick, onFocus } = parameters;
-
-  const { getRootProps: getRootPropsButton, ...otherButtonProps } = useButton(parameters);
+  const { value, ref: externalRef, disabled = false } = parameters;
 
-  const context = useTabContext();
-  if (context === null) {
-    throw new Error('No TabContext provided');
-  }
+  const tabRef = React.useRef<HTMLElement>(null);
 
-  const value = valueProp ?? 0;
-  const selected = context.value === value;
-  const selectionFollowsFocus = context.selectionFollowsFocus;
-
-  const a11yAttributes = {
-    role: 'tab',
-    'aria-controls': getPanelId(context, value) ?? undefined,
-    id: getTabId(context, value) ?? undefined,
-    'aria-selected': selected,
-    disabled: otherButtonProps.disabled,
-  };
+  const { value: selectedValue, idPrefix = '', selectionFollowsFocus } = useTabContext();
 
-  const createHandleFocus =
-    (otherHandlers: EventHandlers) => (event: React.FocusEvent<HTMLButtonElement, Element>) => {
-      otherHandlers.onFocus?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
+  const {
+    getItemProps: getTabProps,
+    getItemState: getTabState,
+    ref: listItemRefHandler,
+  } = useListItem({
+    item: value,
+  });
 
-      if (selectionFollowsFocus && !selected) {
-        if (onChange) {
-          onChange(event, value);
-        }
+  const {
+    getRootProps: getButtonProps,
+    ref: buttonRefHandler,
+    active,
+  } = useButton({
+    disabled,
+    focusableWhenDisabled: !selectionFollowsFocus,
+    type: 'button',
+  });
 
-        context.onSelected(event, value);
-      }
+  const handleRef = useForkRef(tabRef, externalRef, listItemRefHandler, buttonRefHandler);
 
-      if (onFocus) {
-        onFocus(event);
-      }
-    };
+  const tabId = idPrefix + useId();
 
-  const createHandleClick =
-    (otherHandlers: EventHandlers) => (event: React.MouseEvent<Element, MouseEvent>) => {
-      otherHandlers.onClick?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
+  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef }), [disabled, tabRef]);
 
-      if (!selected) {
-        if (onChange) {
-          onChange(event, value);
-        }
-        context.onSelected(event, value);
-      }
+  const { index, totalItemCount: totalTabsCount } = useCompoundItem<string | number, TabMetadata>(
+    value,
+    tabMetadata,
+  );
 
-      if (onClick) {
-        onClick(event);
-      }
-    };
+  const { selected, highlighted } = getTabState();
 
   const getRootProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabRootSlotProps<TOther> => {
-    const buttonResolvedProps = getRootPropsButton({
+    const resolvedTabProps = {
       ...otherHandlers,
-      onClick: createHandleClick(otherHandlers),
-      onFocus: createHandleFocus(otherHandlers),
-    });
+      ...getTabProps(otherHandlers),
+    };
+
+    const resolvedButtonProps = {
+      ...resolvedTabProps,
+      ...getButtonProps(resolvedTabProps),
+    };
 
     return {
-      ...buttonResolvedProps,
-      ...a11yAttributes,
+      ...resolvedButtonProps,
+      role: 'tab',
+      'aria-controls': 'not-implemented-yet',
+      id: tabId,
+      ref: handleRef,
     };
   };
 
   return {
     getRootProps,
-    ...otherButtonProps,
-    selected,
+    active,
+    highlighted,
+    index,
+    // the `selected` state isn't set on the server (it relies on effects to be calculated),
+    // so we fall back to checking the `value` prop with the selectedValue from the TabsContext
+    selected: selected || value === selectedValue,
+    totalTabsCount,
   };
 }
 
diff --git a/packages/mui-base/src/useTab/useTab.types.ts b/packages/mui-base/src/useTab/useTab.types.ts
index 51860160bf67ca..6e0865add74fb0 100644
--- a/packages/mui-base/src/useTab/useTab.types.ts
+++ b/packages/mui-base/src/useTab/useTab.types.ts
@@ -3,63 +3,55 @@ import { UseButtonRootSlotProps } from '../useButton';
 
 export interface UseTabParameters {
   /**
-   * You can provide your own value. Otherwise, we fall back to the child position index.
+   * The value of the tab.
+   * It's used to associate the tab with a tab panel(s) with the same value.
    */
-  value?: number | string;
+  value: number | string;
   /**
-   * Callback invoked when new value is being set.
+   * If `true`, the tab will be disabled.
    */
-  onChange?: (event: React.SyntheticEvent, value: number | string) => void;
-  onClick?: React.MouseEventHandler;
   disabled?: boolean;
-  onFocus?: React.FocusEventHandler;
-  ref: React.Ref<any>;
-}
-
-interface UseTabRootSlotEventHandlers {
-  onClick?: React.MouseEventHandler;
-  onFocus?: React.FocusEventHandler;
+  /**
+   * Ref to the DOM element associated with the tab.
+   */
+  ref?: React.Ref<any>;
 }
 
-export type UseTabRootSlotProps<TOther = {}> = UseButtonRootSlotProps<
-  UseTabRootSlotEventHandlers & TOther
-> & {
+export type UseTabRootSlotProps<TOther = {}> = UseButtonRootSlotProps<TOther> & {
   'aria-controls': React.AriaAttributes['aria-controls'];
   'aria-selected': React.AriaAttributes['aria-selected'];
-  disabled: boolean;
   id: string | undefined;
   role: React.AriaRole;
 };
 
 export interface UseTabReturnValue {
   /**
-   * If `true`, the tab will be selected.
+   * Resolver for the root slot's props.
+   * @param externalProps props for the root slot
+   * @returns props that should be spread on the root slot
    */
-  selected: boolean;
+  getRootProps: <TOther extends Record<string, any> = {}>(
+    externalProps?: TOther,
+  ) => UseTabRootSlotProps<TOther>;
   /**
-   * If `true`, the tab's focus will be visible.
+   * If `true`, the tab is active (as in `:active` pseudo-class; in other words, pressed).
    */
-  focusVisible: boolean;
+  active: boolean;
   /**
-   * Callback for setting the `focusVisible` param.
+   * If `true`, the tab is highlighted.
    */
-  setFocusVisible: React.Dispatch<React.SetStateAction<boolean>>;
+  highlighted: boolean;
   /**
-   * If `true`, the component will be disabled.
-   * @default false
+   * 0-based index of the tab in the list of tabs.
    */
-  disabled: boolean;
+  index: number;
   /**
-   * If `true`, the component will be active.
-   * @default false
+   * If `true`, the tab is selected.
    */
-  active: boolean;
+  selected: boolean;
   /**
-   * Resolver for the root slot's props.
-   * @param externalProps props for the root slot
-   * @returns props that should be spread on the root slot
+   * Total number of tabs in the nearest parent TabsList.
+   * This can be used to determine if the tab is the last one to style it accordingly.
    */
-  getRootProps: <TOther extends Record<string, any> = {}>(
-    externalProps?: TOther,
-  ) => UseTabRootSlotProps<TOther>;
+  totalTabsCount: number;
 }
diff --git a/packages/mui-base/src/useTabs/TabsProvider.tsx b/packages/mui-base/src/useTabs/TabsProvider.tsx
new file mode 100644
index 00000000000000..d2abc1c11ba742
--- /dev/null
+++ b/packages/mui-base/src/useTabs/TabsProvider.tsx
@@ -0,0 +1,59 @@
+import * as React from 'react';
+import TabsContext, { TabsContextValue } from '../TabsUnstyled/TabsContext';
+import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+
+export type TabsProviderValue = CompoundComponentContextValue<string | number, string> &
+  TabsContextValue;
+
+export interface TabsProviderProps {
+  value: TabsProviderValue;
+  children: React.ReactNode;
+}
+
+/**
+ * Sets up the contexts for the underlying Tab and TabPanel components.
+ */
+export default function TabsProvider(props: TabsProviderProps) {
+  const { value: valueProp, children } = props;
+  const {
+    direction,
+    getItemIndex,
+    idPrefix,
+    onSelected,
+    orientation,
+    registerItem,
+    selectionFollowsFocus,
+    totalSubitemCount,
+    unregisterItem,
+    value,
+  } = valueProp;
+
+  const compoundComponentContextValue: CompoundComponentContextValue<string | number, string> =
+    React.useMemo(
+      () => ({
+        getItemIndex,
+        registerItem,
+        totalSubitemCount,
+        unregisterItem,
+      }),
+      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+    );
+
+  const tabsContextValue: TabsContextValue = React.useMemo(
+    () => ({
+      direction,
+      idPrefix,
+      onSelected,
+      orientation,
+      selectionFollowsFocus,
+      value,
+    }),
+    [direction, idPrefix, onSelected, orientation, selectionFollowsFocus, value],
+  );
+
+  return (
+    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
+      <TabsContext.Provider value={tabsContextValue}>{children}</TabsContext.Provider>
+    </CompoundComponentContext.Provider>
+  );
+}
diff --git a/packages/mui-base/src/useTabs/index.ts b/packages/mui-base/src/useTabs/index.ts
index d60002e901e715..7f7e023692592c 100644
--- a/packages/mui-base/src/useTabs/index.ts
+++ b/packages/mui-base/src/useTabs/index.ts
@@ -1,2 +1,6 @@
 export { default } from './useTabs';
+export * from './useTabs';
 export * from './useTabs.types';
+
+export { default as TabsProvider } from './TabsProvider';
+export * from './TabsProvider';
diff --git a/packages/mui-base/src/useTabs/useTabs.ts b/packages/mui-base/src/useTabs/useTabs.ts
index 518bda6bb59bba..de3091963a5798 100644
--- a/packages/mui-base/src/useTabs/useTabs.ts
+++ b/packages/mui-base/src/useTabs/useTabs.ts
@@ -1,6 +1,12 @@
 import * as React from 'react';
 import { unstable_useControlled as useControlled, unstable_useId as useId } from '@mui/utils';
 import { UseTabsParameters, UseTabsReturnValue } from './useTabs.types';
+import useCompoundParent from '../utils/useCompound';
+
+export interface TabMetadata {
+  disabled: boolean;
+  ref: React.RefObject<HTMLElement>;
+}
 
 /**
  *
@@ -32,21 +38,29 @@ function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
   const idPrefix = useId();
 
   const onSelected = React.useCallback(
-    (e: React.SyntheticEvent, newValue: string | number | false) => {
+    (event: React.SyntheticEvent | null, newValue: string | number | null) => {
       setValue(newValue);
-      if (onChange) {
-        onChange(e, newValue);
-      }
+      onChange?.(event, newValue);
     },
     [onChange, setValue],
   );
 
-  const tabsContextValue = React.useMemo(() => {
-    return { idPrefix, value, onSelected, orientation, direction, selectionFollowsFocus };
-  }, [idPrefix, value, onSelected, orientation, direction, selectionFollowsFocus]);
+  const { subitems: tabPanels, ...compoundComponentContextValue } = useCompoundParent<
+    string | number,
+    string
+  >();
 
   return {
-    tabsContextValue,
+    tabPanels,
+    contextValue: {
+      idPrefix,
+      value,
+      onSelected,
+      orientation,
+      direction,
+      selectionFollowsFocus,
+      ...compoundComponentContextValue,
+    },
   };
 }
 
diff --git a/packages/mui-base/src/useTabs/useTabs.types.ts b/packages/mui-base/src/useTabs/useTabs.types.ts
index c0f3ec2da2317f..6ca1f696fb8c2f 100644
--- a/packages/mui-base/src/useTabs/useTabs.types.ts
+++ b/packages/mui-base/src/useTabs/useTabs.types.ts
@@ -1,15 +1,15 @@
-import type { TabsContextValue } from '../TabsUnstyled';
+import { TabsProviderValue } from './TabsProvider';
 
 export interface UseTabsParameters {
   /**
    * The value of the currently selected `Tab`.
    * If you don't want any selected `Tab`, you can set this prop to `false`.
    */
-  value?: string | number | false;
+  value?: string | number | null;
   /**
    * The default value. Use when the component is not controlled.
    */
-  defaultValue?: string | number | false;
+  defaultValue?: string | number | null;
   /**
    * The component orientation (layout flow direction).
    * @default 'horizontal'
@@ -23,7 +23,7 @@ export interface UseTabsParameters {
   /**
    * Callback invoked when new value is being set.
    */
-  onChange?: (event: React.SyntheticEvent, value: number | string | boolean) => void;
+  onChange?: (event: React.SyntheticEvent | null, value: number | string | null) => void;
   /**
    * If `true` the selected tab changes on focus. Otherwise it only
    * changes on activation.
@@ -32,8 +32,9 @@ export interface UseTabsParameters {
 }
 
 export interface UseTabsReturnValue {
+  tabPanels: Map<string | number, string>;
   /**
-   * Returns the values to be passed to the tabs context provider.
+   * Returns the values to be passed to the tabs provider.
    */
-  tabsContextValue: TabsContextValue;
+  contextValue: TabsProviderValue;
 }
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
new file mode 100644
index 00000000000000..c8be55662fbbd6
--- /dev/null
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -0,0 +1,66 @@
+import * as React from 'react';
+import { ListContext, ListContextValue } from '../useListbox';
+import { TabMetadata } from '../useTabs/useTabs';
+import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+
+export type TabsListProviderValue = CompoundComponentContextValue<string | number, TabMetadata> &
+  ListContextValue<string | number>;
+
+export interface TabsListProviderProps {
+  value: TabsListProviderValue;
+  children: React.ReactNode;
+}
+
+/**
+ * Sets up the contexts for the underlying Tab components.
+ */
+export default function TabsListProvider(props: TabsListProviderProps) {
+  const { value, children } = props;
+  const {
+    focusManagement,
+    getItemIndex,
+    getItemProps,
+    getItemState,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+    registerItem,
+    unregisterItem,
+    totalSubitemCount,
+  } = value;
+
+  const listContextValue: ListContextValue<string | number> = React.useMemo(
+    () => ({
+      focusManagement,
+      getItemProps,
+      getItemState,
+      getItemIndex,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    }),
+    [
+      focusManagement,
+      getItemIndex,
+      getItemProps,
+      getItemState,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    ],
+  );
+
+  const compoundComponentContextValue: CompoundComponentContextValue<string | number, TabMetadata> =
+    React.useMemo(
+      () => ({
+        getItemIndex,
+        registerItem,
+        totalSubitemCount,
+        unregisterItem,
+      }),
+      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+    );
+
+  return (
+    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
+      <ListContext.Provider value={listContextValue}>{children}</ListContext.Provider>
+    </CompoundComponentContext.Provider>
+  );
+}
diff --git a/packages/mui-base/src/useTabsList/index.ts b/packages/mui-base/src/useTabsList/index.ts
index 9f0f71e4a5757c..3432c5427462b3 100644
--- a/packages/mui-base/src/useTabsList/index.ts
+++ b/packages/mui-base/src/useTabsList/index.ts
@@ -1,2 +1,5 @@
 export { default } from './useTabsList';
 export * from './useTabsList.types';
+
+export { default as TabsListProvider } from './TabsListProvider';
+export * from './TabsListProvider';
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index bed83ceefa4d3e..156d469ebba4af 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -1,76 +1,23 @@
 import * as React from 'react';
-import {
-  unstable_ownerDocument as ownerDocument,
-  unstable_useForkRef as useForkRef,
-} from '@mui/utils';
-import { isFragment } from 'react-is';
 import { useTabContext } from '../TabsUnstyled';
-import extractEventHandlers from '../utils/extractEventHandlers';
 import {
+  TabsListContextValue,
   UseTabsListParameters,
   UseTabsListReturnValue,
   UseTabsListRootSlotProps,
 } from './useTabsList.types';
 import { EventHandlers } from '../utils';
+import { useCompoundParent } from '../utils/useCompound';
+import { TabMetadata } from '../useTabs/useTabs';
+import useListbox, {
+  ActionTypes,
+  defaultListboxReducer,
+  ListboxReducer,
+  UseListboxParameters,
+} from '../useListbox';
 
-const nextItem = (list: Element | null, item: Element | null): Element | null => {
-  if (!list) {
-    return null;
-  }
-
-  if (list === item) {
-    return list.firstChild as Element | null;
-  }
-  if (item && item.nextElementSibling) {
-    return item.nextElementSibling;
-  }
-  return list.firstChild as Element | null;
-};
-
-const previousItem = (list: Element | null, item: Element | null): Element | null => {
-  if (!list) {
-    return null;
-  }
-
-  if (list === item) {
-    return list.lastChild as Element | null;
-  }
-  if (item && item.previousElementSibling) {
-    return item.previousElementSibling;
-  }
-  return list.lastChild as Element | null;
-};
-
-const moveFocus = (
-  list: Element | null,
-  currentFocus: Element | null,
-  traversalFunction: (list: Element | null, currentFocus: Element | null) => Element | null,
-) => {
-  let wrappedOnce = false;
-  let nextFocus = traversalFunction(list, currentFocus);
-
-  while (list && nextFocus) {
-    // Prevent infinite loop.
-    if (nextFocus === list.firstChild) {
-      if (wrappedOnce) {
-        return;
-      }
-      wrappedOnce = true;
-    }
-
-    // Same logic as useAutocomplete.js
-    const nextFocusDisabled =
-      (nextFocus as any).disabled || nextFocus.getAttribute('aria-disabled') === 'true';
+export const TabsListContext = React.createContext<TabsListContextValue | null>(null);
 
-    if (!nextFocus.hasAttribute('tabindex') || nextFocusDisabled) {
-      // Move to the next element.
-      nextFocus = traversalFunction(list, nextFocus);
-    } else {
-      (nextFocus as any).focus();
-      return;
-    }
-  }
-};
 /**
  *
  * Demos:
@@ -83,134 +30,135 @@ const moveFocus = (
  */
 
 function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue {
-  const { 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, children, ref } = parameters;
+  const { ref: externalRef } = parameters;
+
+  const {
+    direction = 'ltr',
+    onSelected,
+    orientation = 'horizontal',
+    value,
+    selectionFollowsFocus,
+  } = useTabContext();
 
-  const tabsListRef = React.createRef<any>();
-  const handleRef = useForkRef(tabsListRef, ref);
+  const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
+    string | number,
+    TabMetadata
+  >();
 
-  const context = useTabContext();
-  if (context === null) {
-    throw new Error('No TabContext provided');
-  }
+  const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
+
+  const getTabElement = React.useCallback(
+    (tabValue: string | number) => {
+      if (tabValue == null) {
+        return null;
+      }
 
-  const { value, orientation = 'horizontal', direction = 'ltr' } = context;
+      return subitems.get(tabValue)?.ref.current ?? null;
+    },
+    [subitems],
+  );
 
   const isRtl = direction === 'rtl';
 
-  const handleKeyDown = (event: React.KeyboardEvent) => {
-    const list = tabsListRef.current;
-    const currentFocus = ownerDocument(list).activeElement;
-    // Keyboard navigation assumes that [role="tab"] are siblings
-    // though we might warn in the future about nested, interactive elements
-    // as a a11y violation
-    const role = currentFocus?.getAttribute('role');
-    if (role !== 'tab') {
-      return;
-    }
+  let listOrientation: UseListboxParameters<any>['orientation'];
+  if (orientation === 'vertical') {
+    listOrientation = 'vertical';
+  } else {
+    listOrientation = isRtl ? 'horizontal-rtl' : 'horizontal-ltr';
+  }
 
-    let previousItemKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
-    let nextItemKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
-    if (orientation === 'horizontal' && isRtl) {
-      // swap previousItemKey with nextItemKey
-      previousItemKey = 'ArrowRight';
-      nextItemKey = 'ArrowLeft';
-    }
+  const stateReducer: ListboxReducer<string | number> = React.useCallback(
+    (state, action) => {
+      const newState = defaultListboxReducer(state, action);
 
-    switch (event.key) {
-      case previousItemKey:
-        event.preventDefault();
-        moveFocus(list, currentFocus, previousItem);
-        break;
-      case nextItemKey:
-        event.preventDefault();
-        moveFocus(list, currentFocus, nextItem);
-        break;
-      case 'Home':
-        event.preventDefault();
-        moveFocus(list, null, nextItem);
-        break;
-      case 'End':
-        event.preventDefault();
-        moveFocus(list, null, previousItem);
-        break;
-      default:
-        break;
+      if (action.type === ActionTypes.optionsChange) {
+        return {
+          ...newState,
+          highlightedValue: newState.selectedValues[0] ?? null,
+        };
+      }
+
+      if (action.type === ActionTypes.setValue && action.value != null) {
+        return {
+          ...newState,
+          highlightedValue: action.value[0],
+        };
+      }
+
+      if (selectionFollowsFocus && newState.highlightedValue != null) {
+        return {
+          ...newState,
+          selectedValues: [newState.highlightedValue],
+        };
+      }
+
+      return newState;
+    },
+    [selectionFollowsFocus],
+  );
+
+  const listboxValue = React.useMemo(() => {
+    if (value == null) {
+      return [];
     }
-  };
 
-  const createHandleKeyDown =
-    (otherHandlers: Record<string, React.EventHandler<any>>) => (event: React.KeyboardEvent) => {
-      handleKeyDown(event);
-      otherHandlers.onKeyDown?.(event);
-    };
+    return [value];
+  }, [value]);
+
+  const handleChange = React.useCallback(
+    (
+      e:
+        | React.FocusEvent<Element, Element>
+        | React.KeyboardEvent<Element>
+        | React.MouseEvent<Element, MouseEvent>
+        | null,
+      newValue: (string | number)[],
+    ) => {
+      onSelected(e, newValue[0] ?? null);
+    },
+    [onSelected],
+  );
+
+  const {
+    getRootProps: getListboxRootProps,
+    selectedOptions,
+    highlightedOption,
+    contextValue: listContextValue,
+  } = useListbox({
+    disabledItemsFocusable: !selectionFollowsFocus,
+    focusManagement: 'DOM',
+    getOptionElement: getTabElement,
+    isOptionDisabled: (option) => subitems.get(option)?.disabled ?? false,
+    listboxRef: externalRef,
+    onChange: handleChange,
+    options: subitemKeys,
+    orientation: listOrientation,
+    selectionLimit: 1,
+    stateReducer,
+    value: listboxValue,
+  });
 
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabsListRootSlotProps<TOther> => {
-    const propsEventHandlers = extractEventHandlers(parameters);
-    const externalEventHandlers = { ...propsEventHandlers, ...otherHandlers };
-
-    const ownEventHandlers = {
-      onKeyDown: createHandleKeyDown(externalEventHandlers),
-    };
-
-    const mergedEventHandlers = {
-      ...externalEventHandlers,
-      ...ownEventHandlers,
-    };
     return {
-      'aria-label': ariaLabel,
-      'aria-labelledby': ariaLabelledBy,
+      ...otherHandlers,
+      ...getListboxRootProps(otherHandlers),
       'aria-orientation': orientation === 'vertical' ? 'vertical' : undefined,
       role: 'tablist',
-      ref: handleRef,
-      ...mergedEventHandlers,
     };
   };
 
-  const processChildren = React.useCallback(() => {
-    const valueToIndex = new Map();
-
-    let childIndex = 0;
-
-    const processedChildren = React.Children.map(children, (child) => {
-      if (!React.isValidElement(child)) {
-        return null;
-      }
-
-      if (process.env.NODE_ENV !== 'production') {
-        if (isFragment(child)) {
-          console.error(
-            [
-              "MUI: The Tabs component doesn't accept a Fragment as a child.",
-              'Consider providing an array instead.',
-            ].join('\n'),
-          );
-        }
-      }
-
-      const childValue = child.props.value === undefined ? childIndex : child.props.value;
-      valueToIndex.set(childValue, childIndex);
-
-      childIndex += 1;
-
-      return React.cloneElement(child, {
-        value: childValue,
-        ...((childIndex === 1 && value === false && !child.props.tabIndex) || value === childValue
-          ? { tabIndex: 0 }
-          : { tabIndex: -1 }),
-      });
-    });
-
-    return processedChildren;
-  }, [children, value]);
-
   return {
     isRtl,
     orientation,
-    value,
-    processChildren,
+    selectedValue: selectedOptions[0] ?? null,
+    highlightedValue: highlightedOption,
     getRootProps,
+    contextValue: {
+      ...compoundComponentContextValue,
+      ...listContextValue,
+    },
   };
 }
 
diff --git a/packages/mui-base/src/useTabsList/useTabsList.types.ts b/packages/mui-base/src/useTabsList/useTabsList.types.ts
index bb8a1ca7d70edf..009ee6734a6d9c 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.types.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.types.ts
@@ -1,13 +1,23 @@
 import * as React from 'react';
+import { OptionState, UseListboxOptionSlotProps } from '../useListbox';
+import { EventHandlers } from '../utils';
+import { TabsListProviderValue } from './TabsListProvider';
+
+export interface TabsListContextValue {
+  getTabProps: <TOther extends EventHandlers = {}>(
+    tabValue: string | number,
+    otherHandlers?: TOther,
+  ) => UseListboxOptionSlotProps;
+  getTabState: (tabValue: string | number) => OptionState;
+}
 
 export interface UseTabsListParameters {
-  'aria-label'?: string;
-  'aria-labelledby'?: string;
-  /**
-   * The content of the component.
-   */
-  children?: React.ReactNode;
   ref: React.Ref<unknown>;
+  value?: string | number | null;
+  defaultValue?: string | number | null;
+  onChange?: (event: React.SyntheticEvent | null, value: string | number | null) => void;
+  orientation?: 'horizontal' | 'vertical';
+  direction?: 'ltr' | 'rtl';
 }
 
 export type UseTabsListRootSlotProps<TOther = {}> = TOther & {
@@ -20,6 +30,10 @@ export type UseTabsListRootSlotProps<TOther = {}> = TOther & {
 };
 
 export interface UseTabsListReturnValue {
+  /**
+   * The value of the currently highlighted `Tab`.
+   */
+  highlightedValue: string | number | null;
   /**
    * If `true`, it will indicate that the text's direction in right-to-left.
    * @default false
@@ -33,14 +47,7 @@ export interface UseTabsListReturnValue {
   /**
    * The value of the currently selected `Tab`.
    */
-  value: string | number | false;
-  /**
-   * Callback for processing the children of the tabs list. It adds the necessary attributes for correct a11y and navigation.
-   */
-  processChildren: () =>
-    | React.ReactElement<any, string | React.JSXElementConstructor<any>>[]
-    | null
-    | undefined;
+  selectedValue: string | number | null;
   /**
    * Resolver for the root slot's props.
    * @param externalProps props for the root slot
@@ -49,4 +56,8 @@ export interface UseTabsListReturnValue {
   getRootProps: <TOther extends Record<string, any> = {}>(
     externalProps?: TOther,
   ) => UseTabsListRootSlotProps<TOther>;
+  /**
+   * The value to be passed to the TabListProvider above all the tabs.
+   */
+  contextValue: TabsListProviderValue;
 }
diff --git a/packages/mui-base/src/utils/useCompound.test.tsx b/packages/mui-base/src/utils/useCompound.test.tsx
new file mode 100644
index 00000000000000..26357c48c50bdc
--- /dev/null
+++ b/packages/mui-base/src/utils/useCompound.test.tsx
@@ -0,0 +1,170 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { render } from 'test/utils';
+import { CompoundComponentContext, useCompoundParent, useCompoundItem } from './useCompound';
+
+describe('compound components', () => {
+  describe('useCompoundParent', () => {
+    it('knows about children from the whole subtree', () => {
+      let parentSubitems: Map<string, string>;
+
+      function Parent(props: React.PropsWithChildren<{}>) {
+        const { children } = props;
+        const { subitems, contextValue } = useCompoundParent<string, string>();
+
+        parentSubitems = subitems;
+
+        return (
+          <CompoundComponentContext.Provider value={contextValue}>
+            {children}
+          </CompoundComponentContext.Provider>
+        );
+      }
+
+      function Child(props: React.PropsWithChildren<{ id: string; value: string }>) {
+        const { id, value, children } = props;
+        useCompoundItem(id, value);
+
+        return <span>{children}</span>;
+      }
+
+      render(
+        <Parent>
+          <Child id="1" value="one" />
+          <Child id="2" value="two">
+            <Child id="2.1" value="two.one" />
+            <Child id="2.2" value="two.two" />
+          </Child>
+          <Child id="3" value="three">
+            <Child id="3.1" value="three.one">
+              <Child id="3.1.1" value="three.one.one" />
+            </Child>
+          </Child>
+        </Parent>,
+      );
+
+      expect(Array.from(parentSubitems!.keys())).to.deep.equal([
+        '1',
+        '2.1',
+        '2.2',
+        '2',
+        '3.1.1',
+        '3.1',
+        '3',
+      ]);
+
+      expect(Array.from(parentSubitems!.values())).to.deep.equal([
+        'one',
+        'two.one',
+        'two.two',
+        'two',
+        'three.one.one',
+        'three.one',
+        'three',
+      ]);
+    });
+
+    it('knows about children rendered by other components', () => {
+      let parentSubitems: Map<string, string>;
+
+      function Parent(props: React.PropsWithChildren<{}>) {
+        const { children } = props;
+        const { subitems, contextValue } = useCompoundParent<string, string>();
+
+        parentSubitems = subitems;
+
+        return (
+          <CompoundComponentContext.Provider value={contextValue}>
+            {children}
+          </CompoundComponentContext.Provider>
+        );
+      }
+
+      function Child(props: { id: string; value: string }) {
+        const { id, value } = props;
+        useCompoundItem(id, value);
+
+        return <span />;
+      }
+
+      function Wrapper() {
+        return (
+          <React.Fragment>
+            <Child id="1" value="one" />
+            <Child id="2" value="two" />
+            <Child id="3" value="three" />
+          </React.Fragment>
+        );
+      }
+
+      render(
+        <Parent>
+          <Child id="0" value="zero" />
+          <Wrapper />
+          <Child id="4" value="four" />
+        </Parent>,
+      );
+
+      expect(Array.from(parentSubitems!.keys())).to.deep.equal(['0', '1', '2', '3', '4']);
+
+      expect(Array.from(parentSubitems!.values())).to.deep.equal([
+        'zero',
+        'one',
+        'two',
+        'three',
+        'four',
+      ]);
+    });
+
+    // TODO: test if removed children are removed from the map
+
+    // TODO: test if parent is notified about updated metadata
+  });
+
+  describe('useCompoundItem', () => {
+    it('knows its position within the parent and total number of registered items', () => {
+      function Parent(props: React.PropsWithChildren<{}>) {
+        const { children } = props;
+        const { contextValue } = useCompoundParent<string, null>();
+
+        return (
+          <CompoundComponentContext.Provider value={contextValue}>
+            {children}
+          </CompoundComponentContext.Provider>
+        );
+      }
+
+      function Child() {
+        const id = React.useId();
+        const { index, totalItemCount } = useCompoundItem(id, null);
+
+        return (
+          <span data-testid="child">
+            {index + 1} of {totalItemCount}
+          </span>
+        );
+      }
+
+      const { getAllByTestId } = render(
+        <Parent>
+          <Child />
+          <Child />
+          <React.Fragment>
+            <p>Unrelated element 1</p>
+            <Child />
+          </React.Fragment>
+          <p>Unrelated element 2</p>
+          <div>
+            <Child />
+          </div>
+        </Parent>,
+      );
+
+      const children = getAllByTestId('child');
+
+      children.forEach((child, index) => {
+        expect(child.innerHTML).to.equal(`${index + 1} of 4`);
+      });
+    });
+  });
+});
diff --git a/packages/mui-base/src/utils/useCompound.ts b/packages/mui-base/src/utils/useCompound.ts
new file mode 100644
index 00000000000000..0534f0644c70b6
--- /dev/null
+++ b/packages/mui-base/src/utils/useCompound.ts
@@ -0,0 +1,119 @@
+import * as React from 'react';
+
+export type CompoundComponentContextValue<Key, Subitem> = {
+  registerItem: (id: Key, item: Subitem) => void;
+  unregisterItem: (id: Key) => void;
+  getItemIndex: (id: Key) => number;
+  totalSubitemCount: number;
+};
+
+export const CompoundComponentContext = React.createContext<CompoundComponentContextValue<
+  any,
+  any
+> | null>(null);
+
+CompoundComponentContext.displayName = 'CompoundComponentContext';
+
+export interface UseCompoundParentReturnValue<Key, Subitem> {
+  /**
+   * The value for the CompoundComponentContext provider.
+   */
+  contextValue: CompoundComponentContextValue<Key, Subitem>;
+  /**
+   * The subitems registered with the parent.
+   * The key is the id of the subitem, and the value is the metadata passed to the `useCompoundItem` hook.
+   * The order of the items is the same as the order in which they were registered.
+   */
+  subitems: Map<Key, Subitem>;
+}
+
+/**
+ * Provides a way for a component to know about its children.
+ *
+ * Child components register themselves with the `useCompoundItem` hook, passing in arbitrary metadata to the parent.
+ *
+ * This is a more powerful altervantive to `children` traversal, as child components don't have to be placed
+ * directly inside the parent component. They can be anywhere in the tree (and even rendered by other components).
+ *
+ * The downside is that this doesn't work with SSR as it relies on the useEffect hook.
+ */
+export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<Key, Subitem> {
+  const [subitems, setSubitems] = React.useState(new Map<Key, Subitem>());
+
+  const registerItem = React.useCallback(function registerItem(id: Key, item: Subitem) {
+    setSubitems((previousState) => {
+      const newState = new Map(previousState);
+      newState.set(id, item);
+      return newState;
+    });
+  }, []);
+
+  const unregisterItem = React.useCallback(function unregisterItem(id: Key) {
+    setSubitems((previousState) => {
+      const newState = new Map(previousState);
+      newState.delete(id);
+      return newState;
+    });
+  }, []);
+
+  const getItemIndex = React.useCallback(
+    function getItemIndex(id: Key) {
+      return Array.from(subitems.keys()).indexOf(id);
+    },
+    [subitems],
+  );
+
+  return {
+    contextValue: {
+      getItemIndex,
+      registerItem,
+      totalSubitemCount: subitems.size,
+      unregisterItem,
+    },
+    subitems,
+  };
+}
+
+export interface UseCompoundItemReturnValue {
+  /**
+   * The 0-based index of the child component in the parent component's list of registered children.
+   */
+  index: number;
+  /**
+   * The total number of child components registered with the parent component.
+   */
+  totalItemCount: number;
+}
+
+/**
+ * Registers a child component with the parent component.
+ *
+ * @param id A unique key for the child component
+ * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
+ */
+export function useCompoundItem<Key, Subitem>(
+  id: Key,
+  itemMetadata: Subitem,
+): UseCompoundItemReturnValue {
+  const context = React.useContext(CompoundComponentContext) as CompoundComponentContextValue<
+    Key,
+    Subitem
+  >;
+
+  if (context === null) {
+    throw new Error('useCompoundItem must be used within a useCompoundParent');
+  }
+
+  const { registerItem, unregisterItem } = context;
+
+  React.useEffect(() => {
+    registerItem(id, itemMetadata);
+
+    return () => unregisterItem(id);
+  }, [id, registerItem, unregisterItem, itemMetadata]);
+
+  return {
+    index: context.getItemIndex(id),
+    totalItemCount: context.totalSubitemCount,
+  };
+}
diff --git a/packages/mui-base/src/utils/useMessageBus.test.ts b/packages/mui-base/src/utils/useMessageBus.test.ts
index eead0e9b6f40d2..dbdbe977b3f525 100644
--- a/packages/mui-base/src/utils/useMessageBus.test.ts
+++ b/packages/mui-base/src/utils/useMessageBus.test.ts
@@ -5,38 +5,44 @@ import { createMessageBus } from './useMessageBus';
 describe('messageBus', () => {
   it('should be able to subscribe to a message', () => {
     const { subscribe, publish } = createMessageBus();
+    const testSubject = Symbol('test');
     const callback = spy();
-    subscribe('test', callback);
-    publish('test', 'foo');
+    subscribe(testSubject, callback);
+    publish(testSubject, 'foo');
     expect(callback.args[0][0]).to.equal('foo');
   });
 
   it('should be able to unsubscribe from a message', () => {
     const { subscribe, publish } = createMessageBus();
+    const testSubject = Symbol('test');
     const callback = spy();
-    const unsubscribe = subscribe('test', callback);
+    const unsubscribe = subscribe(testSubject, callback);
     unsubscribe();
-    publish('test', 'foo');
+    publish(testSubject, 'foo');
     expect(callback.callCount).to.equal(0);
   });
 
   it('should be able to publish multiple messages', () => {
     const { subscribe, publish } = createMessageBus();
+    const testSubject1 = Symbol('test1');
+    const testSubject2 = Symbol('test2');
     const callback = spy();
-    subscribe('test', callback);
-    subscribe('test2', callback);
-    publish('test', 'foo');
-    publish('test2', 'foo');
+    subscribe(testSubject1, callback);
+    subscribe(testSubject2, callback);
+    publish(testSubject1, 'foo');
+    publish(testSubject2, 'foo');
     expect(callback.callCount).to.equal(2);
   });
 
   it('should be able to publish multiple messages with different arguments', () => {
     const { subscribe, publish } = createMessageBus();
+    const testSubject1 = Symbol('test1');
+    const testSubject2 = Symbol('test2');
     const callback = spy();
-    subscribe('test', callback);
-    subscribe('test2', callback);
-    publish('test', 'foo');
-    publish('test2', 'bar');
+    subscribe(testSubject1, callback);
+    subscribe(testSubject2, callback);
+    publish(testSubject1, 'foo');
+    publish(testSubject2, 'bar');
     expect(callback.args[0][0]).to.equal('foo');
     expect(callback.args[1][0]).to.equal('bar');
   });
diff --git a/packages/mui-joy/src/TabList/TabList.tsx b/packages/mui-joy/src/TabList/TabList.tsx
index c56593fb4b026f..3957eb9e518ec0 100644
--- a/packages/mui-joy/src/TabList/TabList.tsx
+++ b/packages/mui-joy/src/TabList/TabList.tsx
@@ -3,7 +3,7 @@ import PropTypes from 'prop-types';
 import { unstable_capitalize as capitalize } from '@mui/utils';
 import { unstable_composeClasses as composeClasses } from '@mui/base';
 import { OverridableComponent } from '@mui/types';
-import useTabsList from '@mui/base/useTabsList';
+import useTabsList, { TabsListProvider } from '@mui/base/useTabsList';
 import { useSlotProps } from '@mui/base/utils';
 import { useThemeProps } from '../styles';
 import styled from '../styles/styled';
@@ -71,7 +71,9 @@ const TabList = React.forwardRef(function TabList(inProps, ref) {
   const { getColor } = useColorInversion(variant);
   const color = getColor(inProps.color, colorProp);
 
-  const { isRtl, orientation, getRootProps, processChildren } = useTabsList({ ...props, ref });
+  const { isRtl, orientation, getRootProps, contextValue } = useTabsList({
+    ref,
+  });
 
   const size = sizeProp ?? tabsSize;
 
@@ -99,14 +101,14 @@ const TabList = React.forwardRef(function TabList(inProps, ref) {
     className: classes.root,
   });
 
-  const processedChildren = processChildren();
-
   return (
     // @ts-ignore conflicted ref types
     <TabListRoot {...tabsListRootProps}>
-      <ListProvider row={orientation === 'horizontal'} nested>
-        {processedChildren}
-      </ListProvider>
+      <TabsListProvider value={contextValue}>
+        <ListProvider row={orientation === 'horizontal'} nested>
+          {children}
+        </ListProvider>
+      </TabsListProvider>
     </TabListRoot>
   );
 }) as OverridableComponent<TabListTypeMap>;
diff --git a/packages/mui-joy/src/Tabs/Tabs.tsx b/packages/mui-joy/src/Tabs/Tabs.tsx
index 9e2d232ace4719..393bec23436d6d 100644
--- a/packages/mui-joy/src/Tabs/Tabs.tsx
+++ b/packages/mui-joy/src/Tabs/Tabs.tsx
@@ -3,8 +3,7 @@ import PropTypes from 'prop-types';
 import { unstable_capitalize as capitalize } from '@mui/utils';
 import { unstable_composeClasses as composeClasses } from '@mui/base';
 import { OverridableComponent } from '@mui/types';
-import useTabs from '@mui/base/useTabs';
-import { TabsContext } from '@mui/base/TabsUnstyled';
+import useTabs, { TabsProvider } from '@mui/base/useTabs';
 import { useSlotProps } from '@mui/base/utils';
 import { SheetRoot } from '../Sheet/Sheet';
 import { styled, useThemeProps } from '../styles';
@@ -83,7 +82,7 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
   const { getColor } = useColorInversion(variant);
   const color = getColor(inProps.color, colorProp);
   const defaultValue = defaultValueProp || (valueProp === undefined ? 0 : undefined);
-  const { tabsContextValue } = useTabs({ ...props, orientation, defaultValue });
+  const { contextValue } = useTabs({ ...props, orientation, defaultValue });
 
   const ownerState = {
     ...props,
@@ -111,9 +110,9 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
   return (
     // @ts-ignore `defaultValue` between HTMLDiv and TabsProps is conflicted.
     <TabsRoot {...tabsRootProps}>
-      <TabsContext.Provider value={tabsContextValue}>
+      <TabsProvider value={contextValue}>
         <SizeTabsContext.Provider value={size}>{children}</SizeTabsContext.Provider>
-      </TabsContext.Provider>
+      </TabsProvider>
     </TabsRoot>
   );
 }) as OverridableComponent<TabsTypeMap>;

From 4cf59eaccb96fad33a146d5245c549f4cbde917e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 15 Mar 2023 19:22:33 +0100
Subject: [PATCH 03/49] Extract useListItem to a separate file

---
 packages/mui-base/src/useListbox/index.ts     |  6 +-
 .../mui-base/src/useListbox/useListItem.ts    | 80 +++++++++++++++++++
 .../mui-base/src/useListbox/useListbox.ts     | 73 -----------------
 3 files changed, 85 insertions(+), 74 deletions(-)
 create mode 100644 packages/mui-base/src/useListbox/useListItem.ts

diff --git a/packages/mui-base/src/useListbox/index.ts b/packages/mui-base/src/useListbox/index.ts
index 7f76c2e2e7eeb1..fc75df9d190a10 100644
--- a/packages/mui-base/src/useListbox/index.ts
+++ b/packages/mui-base/src/useListbox/index.ts
@@ -1,5 +1,9 @@
 export { default } from './useListbox';
 export * from './useListbox';
-export { default as defaultListboxReducer } from './defaultListboxReducer';
+
+export { default as useListItem } from './useListItem';
+export * from './useListItem';
 
 export * from './useListbox.types';
+
+export { default as defaultListboxReducer } from './defaultListboxReducer';
diff --git a/packages/mui-base/src/useListbox/useListItem.ts b/packages/mui-base/src/useListbox/useListItem.ts
new file mode 100644
index 00000000000000..f549bd326e9c43
--- /dev/null
+++ b/packages/mui-base/src/useListbox/useListItem.ts
@@ -0,0 +1,80 @@
+import * as React from 'react';
+import {
+  unstable_useForkRef as useForkRef,
+  unstable_useEnhancedEffect as useEnhancedEffect,
+} from '@mui/utils';
+import { EventHandlers } from '../utils/types';
+import useForcedRerendering from '../utils/useForcedRerendering';
+import { ListContext } from './useListbox';
+
+export interface UseListItemParameters<Item> {
+  item: Item;
+  ref?: React.Ref<HTMLElement>;
+}
+
+export default function useListItem<Item>(parameters: UseListItemParameters<Item>) {
+  const { item, ref: externalRef } = parameters;
+
+  const itemRef = React.useRef<HTMLElement>(null);
+  const handleRef = useForkRef(itemRef, externalRef);
+
+  const listContext = React.useContext(ListContext);
+  if (!listContext) {
+    throw new Error('useListItem must be used within a ListProvider');
+  }
+
+  const {
+    getItemProps,
+    getItemState,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+  } = listContext;
+
+  const itemState = getItemState(item);
+  const { highlighted, selected } = itemState;
+
+  const rerender = useForcedRerendering();
+
+  useEnhancedEffect(() => {
+    function updateHighlightedState(highlightedItem: Item | null) {
+      if (highlightedItem === item && !highlighted) {
+        rerender();
+      } else if (highlightedItem !== item && highlighted) {
+        rerender();
+      }
+    }
+
+    return registerHighlightChangeHandler(updateHighlightedState);
+  });
+
+  useEnhancedEffect(() => {
+    function updateSelectedState(selectedItems: Item | Item[] | null) {
+      if (!selected) {
+        if (Array.isArray(selectedItems)) {
+          if (selectedItems.includes(item)) {
+            rerender();
+          }
+        } else if (selectedItems === item) {
+          rerender();
+        }
+      } else if (Array.isArray(selectedItems)) {
+        if (!selectedItems.includes(item)) {
+          rerender();
+        }
+      } else if (selectedItems !== item) {
+        rerender();
+      }
+    }
+
+    return registerSelectionChangeHandler(updateSelectedState);
+  }, [registerSelectionChangeHandler, rerender, selected, item]);
+
+  return {
+    getItemProps: <TOther extends EventHandlers = {}>(otherHandlers?: TOther) => ({
+      ...getItemProps(item, otherHandlers),
+      ref: handleRef,
+    }),
+    getItemState: () => getItemState(item),
+    ref: handleRef,
+  };
+}
diff --git a/packages/mui-base/src/useListbox/useListbox.ts b/packages/mui-base/src/useListbox/useListbox.ts
index 4a4570e28fdca8..aff34f398da671 100644
--- a/packages/mui-base/src/useListbox/useListbox.ts
+++ b/packages/mui-base/src/useListbox/useListbox.ts
@@ -14,7 +14,6 @@ import areArraysEqual from '../utils/areArraysEqual';
 import { EventHandlers } from '../utils/types';
 import useLatest from '../utils/useLatest';
 import useTextNavigation from '../utils/useTextNavigation';
-import useForcedRerendering from '../utils/useForcedRerendering';
 import useListChangeNotifiers from './useListChangeNotifiers';
 
 const defaultOptionComparer = <TOption>(optionA: TOption, optionB: TOption) => optionA === optionB;
@@ -437,75 +436,3 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     contextValue,
   };
 }
-
-export interface UseListItemParameters<Item> {
-  item: Item;
-  ref?: React.Ref<HTMLElement>;
-}
-
-export function useListItem<Item>(parameters: UseListItemParameters<Item>) {
-  const { item, ref: externalRef } = parameters;
-
-  const itemRef = React.useRef<HTMLElement>(null);
-  const handleRef = useForkRef(itemRef, externalRef);
-
-  const listContext = React.useContext(ListContext);
-  if (!listContext) {
-    throw new Error('useListItem must be used within a ListProvider');
-  }
-
-  const {
-    getItemProps,
-    getItemState,
-    registerHighlightChangeHandler,
-    registerSelectionChangeHandler,
-  } = listContext;
-
-  const itemState = getItemState(item);
-  const { highlighted, selected } = itemState;
-
-  const rerender = useForcedRerendering();
-
-  React.useEffect(() => {
-    function updateHighlightedState(highlightedItem: Item | null) {
-      if (highlightedItem === item && !highlighted) {
-        rerender();
-      } else if (highlightedItem !== item && highlighted) {
-        rerender();
-      }
-    }
-
-    return registerHighlightChangeHandler(updateHighlightedState);
-  });
-
-  React.useEffect(() => {
-    function updateSelectedState(selectedItems: Item | Item[] | null) {
-      if (!selected) {
-        if (Array.isArray(selectedItems)) {
-          if (selectedItems.includes(item)) {
-            rerender();
-          }
-        } else if (selectedItems === item) {
-          rerender();
-        }
-      } else if (Array.isArray(selectedItems)) {
-        if (!selectedItems.includes(item)) {
-          rerender();
-        }
-      } else if (selectedItems !== item) {
-        rerender();
-      }
-    }
-
-    return registerSelectionChangeHandler(updateSelectedState);
-  }, [registerSelectionChangeHandler, rerender, selected, item]);
-
-  return {
-    getItemProps: <TOther extends EventHandlers = {}>(otherHandlers?: TOther) => ({
-      ...getItemProps(item, otherHandlers),
-      ref: handleRef,
-    }),
-    getItemState: () => getItemState(item),
-    ref: handleRef,
-  };
-}

From ce1aeac6738fe9d886e60ffda389ec0bff1c0df1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 16 Mar 2023 22:55:07 +0100
Subject: [PATCH 04/49] Clean up useListbox

---
 .../mui-base/src/useListbox/actions.types.ts  |  77 +++++
 .../useListbox/defaultListboxReducer.test.ts  | 255 ++++++++--------
 .../src/useListbox/defaultListboxReducer.ts   | 267 +++++++++--------
 packages/mui-base/src/useListbox/index.ts     |   4 +-
 .../useControllableReducer.test.tsx           |  58 ++--
 .../src/useListbox/useControllableReducer.ts  |  32 +--
 .../src/useListbox/useListChangeNotifiers.ts  |  10 +-
 .../mui-base/src/useListbox/useListItem.ts    | 103 +++++--
 .../src/useListbox/useListItem.types.ts       |  50 ++++
 .../src/useListbox/useListbox.test.tsx        |  43 +--
 .../mui-base/src/useListbox/useListbox.ts     | 271 +++++++-----------
 .../src/useListbox/useListbox.types.ts        | 200 ++++---------
 packages/mui-joy/src/Option/OptionProps.ts    |   4 +-
 13 files changed, 694 insertions(+), 680 deletions(-)
 create mode 100644 packages/mui-base/src/useListbox/actions.types.ts
 create mode 100644 packages/mui-base/src/useListbox/useListItem.types.ts

diff --git a/packages/mui-base/src/useListbox/actions.types.ts b/packages/mui-base/src/useListbox/actions.types.ts
new file mode 100644
index 00000000000000..14244219272452
--- /dev/null
+++ b/packages/mui-base/src/useListbox/actions.types.ts
@@ -0,0 +1,77 @@
+enum ActionTypes {
+  blur = 'blur',
+  focus = 'focus',
+  keyDown = 'keyDown',
+  itemClick = 'itemClick',
+  itemHover = 'itemHover',
+  itemsChange = 'itemsChange',
+  setValue = 'setValue',
+  setHighlight = 'setHighlight',
+  textNavigation = 'textNagivation',
+}
+
+// split declaration and export due to https://github.com/codesandbox/codesandbox-client/issues/6435
+export { ActionTypes };
+
+interface ItemClickAction<Value> {
+  type: ActionTypes.itemClick;
+  item: Value;
+  event: React.MouseEvent;
+}
+
+interface ItemHoverAction<Value> {
+  type: ActionTypes.itemHover;
+  item: Value;
+  event: React.MouseEvent;
+}
+
+interface FocusAction {
+  type: ActionTypes.focus;
+  event: React.FocusEvent;
+}
+
+interface BlurAction {
+  type: ActionTypes.blur;
+  event: React.FocusEvent;
+}
+
+interface KeyDownAction {
+  type: ActionTypes.keyDown;
+  event: React.KeyboardEvent;
+}
+
+interface SetValueAction<Value> {
+  type: ActionTypes.setValue;
+  event: null;
+  values: Value[];
+}
+
+interface SetHighlightAction<Value> {
+  type: ActionTypes.setHighlight;
+  event: null;
+  value: Value | null;
+}
+
+interface TextNavigationAction {
+  type: ActionTypes.textNavigation;
+  event: React.KeyboardEvent;
+  searchString: string;
+}
+
+interface ItemsChangeAction<Value> {
+  type: ActionTypes.itemsChange;
+  event: null;
+  items: Value[];
+  previousItems: Value[];
+}
+
+export type ListAction<Value> =
+  | ItemClickAction<Value>
+  | ItemHoverAction<Value>
+  | FocusAction
+  | BlurAction
+  | KeyDownAction
+  | SetHighlightAction<Value>
+  | TextNavigationAction
+  | SetValueAction<Value>
+  | ItemsChangeAction<Value>;
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
index 6f2ccd7fe84b2f..505e780d238eed 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
@@ -1,27 +1,28 @@
 import * as React from 'react';
 import { expect } from 'chai';
-import { ActionTypes, ListboxReducerAction, ListboxState } from './useListbox.types';
+import { ListReducerAction, ListState } from './useListbox.types';
+import { ActionTypes } from './actions.types';
 import defaultReducer from './defaultListboxReducer';
 
 describe('useListbox defaultReducer', () => {
   describe('action: setControlledValue', () => {
     it("assigns the provided value to the state's selectedValues", () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.setValue,
-        value: ['foo'],
+        values: ['foo'],
         event: null,
         props: {
-          options: ['foo', 'bar'],
+          items: ['foo', 'bar'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -33,21 +34,21 @@ describe('useListbox defaultReducer', () => {
 
   describe('action: blur', () => {
     it('resets the highlightedIndex', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.blur,
         event: {} as any, // not relevant
         props: {
-          options: [],
+          items: [],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -60,25 +61,25 @@ describe('useListbox defaultReducer', () => {
 
   describe('action: optionClick', () => {
     it('sets the selectedValues to the clicked value', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
-        type: ActionTypes.optionClick,
+      const action: ListReducerAction<string> = {
+        type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          options: ['one', 'two', 'three'],
+          items: ['one', 'two', 'three'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
-        option: 'two',
+        item: 'two',
       };
 
       const result = defaultReducer(state, action);
@@ -86,25 +87,25 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('replaces the selectedValues with the clicked value if selectionLimit = 1', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: ['one'],
       };
 
-      const action: ListboxReducerAction<string> = {
-        type: ActionTypes.optionClick,
+      const action: ListReducerAction<string> = {
+        type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          options: ['one', 'two', 'three'],
+          items: ['one', 'two', 'three'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: 1,
         },
-        option: 'two',
+        item: 'two',
       };
 
       const result = defaultReducer(state, action);
@@ -112,25 +113,25 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('add the clicked value to the selection if selectionLimit is not set', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'one',
         selectedValues: ['one'],
       };
 
-      const action: ListboxReducerAction<string> = {
-        type: ActionTypes.optionClick,
+      const action: ListReducerAction<string> = {
+        type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          options: ['one', 'two', 'three'],
+          items: ['one', 'two', 'three'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
-        option: 'two',
+        item: 'two',
       };
 
       const result = defaultReducer(state, action);
@@ -138,25 +139,25 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('remove the clicked value from the selection if selectionLimit is not set and it was selected already', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'three',
         selectedValues: ['one', 'two'],
       };
 
-      const action: ListboxReducerAction<string> = {
-        type: ActionTypes.optionClick,
+      const action: ListReducerAction<string> = {
+        type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          options: ['one', 'two', 'three'],
+          items: ['one', 'two', 'three'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
-        option: 'two',
+        item: 'two',
       };
 
       const result = defaultReducer(state, action);
@@ -167,23 +168,23 @@ describe('useListbox defaultReducer', () => {
   describe('action: keyDown', () => {
     describe('Home key is pressed', () => {
       it('highlights the first non-disabled option if the first is disabled', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: null,
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Home',
           } as any,
           props: {
-            options: ['one', 'two', 'three', 'four', 'five'],
+            items: ['one', 'two', 'three', 'four', 'five'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: (_, index) => index === 0,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: (_, index) => index === 0,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -196,23 +197,23 @@ describe('useListbox defaultReducer', () => {
 
     describe('End key is pressed', () => {
       it('highlights the last non-disabled option if the last is disabled', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: null,
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'End',
           } as any,
           props: {
-            options: ['one', 'two', 'three', 'four', 'five'],
+            items: ['one', 'two', 'three', 'four', 'five'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: (_, index) => index === 4,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: (_, index) => index === 4,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -225,23 +226,23 @@ describe('useListbox defaultReducer', () => {
 
     describe('ArrowUp key is pressed', () => {
       it('wraps the highlight around omitting disabled items', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: null,
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowUp',
           } as any,
           props: {
-            options: ['one', 'two', 'three', 'four', 'five'],
+            items: ['one', 'two', 'three', 'four', 'five'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: (_, index) => index === 0 || index === 4,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: (_, index) => index === 0 || index === 4,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -254,23 +255,23 @@ describe('useListbox defaultReducer', () => {
 
     describe('ArrowDown key is pressed', () => {
       it('wraps the highlight around omitting disabled items', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: null,
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
           props: {
-            options: ['one', 'two', 'three', 'four', 'five'],
+            items: ['one', 'two', 'three', 'four', 'five'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: (_, index) => index === 0 || index === 4,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: (_, index) => index === 0 || index === 4,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -281,23 +282,23 @@ describe('useListbox defaultReducer', () => {
       });
 
       it('does not highlight any option if all are disabled', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: null,
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
           props: {
-            options: ['one', 'two', 'three', 'four', 'five'],
+            items: ['one', 'two', 'three', 'four', 'five'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: () => true,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: () => true,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -310,23 +311,23 @@ describe('useListbox defaultReducer', () => {
 
     describe('Enter key is pressed', () => {
       it('selects the highlighted option', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: [],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            options: ['one', 'two', 'three'],
+            items: ['one', 'two', 'three'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: () => false,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
@@ -337,23 +338,23 @@ describe('useListbox defaultReducer', () => {
       });
 
       it('replaces the selectedValues with the highlighted value if selectionLimit = 1', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
         };
 
-        const action: ListboxReducerAction<string> = {
+        const action: ListReducerAction<string> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            options: ['one', 'two', 'three'],
+            items: ['one', 'two', 'three'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: () => false,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: 1,
           },
@@ -364,27 +365,27 @@ describe('useListbox defaultReducer', () => {
       });
 
       it('add the highlighted value to the selection if selectionLimit is not set', () => {
-        const state: ListboxState<string> = {
+        const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
         };
 
-        const action: ListboxReducerAction<string> = {
-          type: ActionTypes.optionClick,
+        const action: ListReducerAction<string> = {
+          type: ActionTypes.itemClick,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            options: ['one', 'two', 'three'],
+            items: ['one', 'two', 'three'],
             disableListWrap: false,
             disabledItemsFocusable: false,
-            isOptionDisabled: () => false,
-            optionComparer: (o, v) => o === v,
-            optionStringifier: (option) => option,
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
             orientation: 'vertical',
             selectionLimit: null,
           },
-          option: 'two',
+          item: 'two',
         };
 
         const result = defaultReducer(state, action);
@@ -395,22 +396,22 @@ describe('useListbox defaultReducer', () => {
 
   describe('action: textNavigation', () => {
     it('should navigate to next match', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'two',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.textNavigation,
         searchString: 'th',
         event: {} as React.KeyboardEvent,
         props: {
-          options: ['one', 'two', 'three', 'four', 'five'],
+          items: ['one', 'two', 'three', 'four', 'five'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -420,23 +421,23 @@ describe('useListbox defaultReducer', () => {
       expect(result.highlightedValue).to.equal('three');
     });
 
-    it('should not move highlight when no matched options', () => {
-      const state: ListboxState<string> = {
+    it('should not move the highlight when there are no matched items', () => {
+      const state: ListState<string> = {
         highlightedValue: 'one',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.textNavigation,
         searchString: 'z',
         event: {} as React.KeyboardEvent,
         props: {
-          options: ['one', 'two', 'three', 'four', 'five'],
+          items: ['one', 'two', 'three', 'four', 'five'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -447,22 +448,22 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('should highlight first match that is not disabled', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'one',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
-          options: ['one', 'two', 'three', 'four', 'five'],
+          items: ['one', 'two', 'three', 'four', 'five'],
           disableListWrap: false,
           disabledItemsFocusable: false,
-          isOptionDisabled: (_, i) => i === 1,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: (_, i) => i === 1,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -473,22 +474,22 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('should move highlight to disabled items if disabledItemsFocusable=true', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'one',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
-          options: ['one', 'two', 'three', 'four', 'five'],
+          items: ['one', 'two', 'three', 'four', 'five'],
           disableListWrap: false,
           disabledItemsFocusable: true,
-          isOptionDisabled: (_, i) => i === 1,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: (_, i) => i === 1,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
@@ -499,22 +500,22 @@ describe('useListbox defaultReducer', () => {
     });
 
     it('should not move highlight when disabled wrap and match is before highlighted option', () => {
-      const state: ListboxState<string> = {
+      const state: ListState<string> = {
         highlightedValue: 'three',
         selectedValues: [],
       };
 
-      const action: ListboxReducerAction<string> = {
+      const action: ListReducerAction<string> = {
         type: ActionTypes.textNavigation,
         searchString: 'one',
         event: {} as React.KeyboardEvent,
         props: {
-          options: ['one', 'two', 'three', 'four', 'five'],
+          items: ['one', 'two', 'three', 'four', 'five'],
           disableListWrap: true,
           disabledItemsFocusable: false,
-          isOptionDisabled: () => false,
-          optionComparer: (o, v) => o === v,
-          optionStringifier: (option) => option,
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
           orientation: 'vertical',
           selectionLimit: null,
         },
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.ts b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
index e24c16545b4b15..8e42ec0f94d667 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useListbox/defaultListboxReducer.ts
@@ -1,45 +1,40 @@
 import * as React from 'react';
-import {
-  ListboxState,
-  UseListboxParametersWithDefaults,
-  ActionTypes,
-  ListboxReducerAction,
-} from './useListbox.types';
+import { ActionTypes } from './actions.types';
+import { ListState, UseListParametersWithDefaults, ListReducerAction } from './useListbox.types';
 
-type OptionPredicate<TOption> = (option: TOption, index: number) => boolean;
+type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
+// TODO: make page size configurable
 const pageSize = 5;
 
-function findValidOptionToHighlight<TOption>(
+function findValidItemToHighlight<ItemValue>(
   index: number,
   lookupDirection: 'next' | 'previous',
-  options: TOption[],
+  items: ItemValue[],
   focusDisabled: boolean,
-  isOptionDisabled: OptionPredicate<TOption>,
+  isItemDisabled: ItemPredicate<ItemValue>,
   wrapAround: boolean,
 ): number {
-  if (options.length === 0 || options.every((o, i) => isOptionDisabled(o, i))) {
+  if (items.length === 0 || items.every((item, itemIndex) => isItemDisabled(item, itemIndex))) {
     return -1;
   }
 
   let nextFocus = index;
 
   for (;;) {
-    // No valid options found
+    // No valid items found
     if (
-      (!wrapAround && lookupDirection === 'next' && nextFocus === options.length) ||
+      (!wrapAround && lookupDirection === 'next' && nextFocus === items.length) ||
       (!wrapAround && lookupDirection === 'previous' && nextFocus === -1)
     ) {
       return -1;
     }
 
-    const nextFocusDisabled = focusDisabled
-      ? false
-      : isOptionDisabled(options[nextFocus], nextFocus);
+    const nextFocusDisabled = focusDisabled ? false : isItemDisabled(items[nextFocus], nextFocus);
     if (nextFocusDisabled) {
       nextFocus += lookupDirection === 'next' ? 1 : -1;
       if (wrapAround) {
-        nextFocus = (nextFocus + options.length) % options.length;
+        nextFocus = (nextFocus + items.length) % items.length;
       }
     } else {
       return nextFocus;
@@ -47,21 +42,21 @@ function findValidOptionToHighlight<TOption>(
   }
 }
 
-function getNewHighlightedOption<TOption>(
-  options: TOption[],
-  previouslyHighlightedOption: TOption | null,
+function getNewHighlightedItem<ItemValue>(
+  items: ItemValue[],
+  previouslyHighlightedValue: ItemValue | null,
   diff: number | 'reset' | 'start' | 'end',
-  highlightDisabledOptions: boolean,
-  isOptionDisabled: OptionPredicate<TOption>,
+  highlightDisabledItems: boolean,
+  isItemDisabled: ItemPredicate<ItemValue>,
   disableListWrap: boolean,
-  optionComparer: (optionA: TOption, optionB: TOption) => boolean,
-): TOption | null {
-  const maxIndex = options.length - 1;
+  itemComparer: (item1: ItemValue, item2: ItemValue) => boolean,
+): ItemValue | null {
+  const maxIndex = items.length - 1;
   const defaultHighlightedIndex = -1;
   const previouslyHighlightedIndex =
-    previouslyHighlightedOption == null
+    previouslyHighlightedValue == null
       ? -1
-      : options.findIndex((option) => optionComparer(option, previouslyHighlightedOption));
+      : items.findIndex((item) => itemComparer(item, previouslyHighlightedValue));
 
   let nextIndexCandidate: number;
   let lookupDirection: 'next' | 'previous';
@@ -117,105 +112,100 @@ function getNewHighlightedOption<TOption>(
     }
   }
 
-  const nextIndex = findValidOptionToHighlight(
+  const nextIndex = findValidItemToHighlight(
     nextIndexCandidate,
     lookupDirection,
-    options,
-    highlightDisabledOptions,
-    isOptionDisabled,
+    items,
+    highlightDisabledItems,
+    isItemDisabled,
     wrapAround,
   );
 
-  return options[nextIndex] ?? null;
+  return items[nextIndex] ?? null;
 }
 
-function moveHighlight<TOption>(
-  previouslyHighlightedOption: TOption | null,
+function moveHighlight<ItemValue>(
+  previouslyHighlightedValue: ItemValue | null,
   diff: number | 'reset' | 'start' | 'end',
-  props: UseListboxParametersWithDefaults<TOption>,
+  props: UseListParametersWithDefaults<ItemValue>,
 ) {
-  const { options, isOptionDisabled, disableListWrap, disabledItemsFocusable, optionComparer } =
-    props;
+  const { items, isItemDisabled, disableListWrap, disabledItemsFocusable, itemComparer } = props;
 
-  return getNewHighlightedOption(
-    options,
-    previouslyHighlightedOption,
+  return getNewHighlightedItem(
+    items,
+    previouslyHighlightedValue,
     diff,
     disabledItemsFocusable ?? false,
-    isOptionDisabled ?? (() => false),
+    isItemDisabled ?? (() => false),
     disableListWrap ?? false,
-    optionComparer ?? ((o1, o2) => o1 === o2),
+    itemComparer ?? ((o1, o2) => o1 === o2),
   );
 }
 
-function toggleSelection<TOption>(
-  option: TOption,
-  selectedOptions: TOption[],
+function toggleSelection<ItemValue>(
+  item: ItemValue,
+  selectedValues: ItemValue[],
   selectionLimit: number | null,
-  optionComparer: (optionA: TOption, optionB: TOption) => boolean,
+  itemComparer: (item1: ItemValue, item2: ItemValue) => boolean,
 ) {
   if (selectionLimit === 0) {
     return [];
   }
 
-  // Selection limit = 1 is a special case - we don't want to allow deselecting the option.
+  // Selection limit = 1 is a special case - we don't want to allow deselecting the item.
   if (selectionLimit === 1) {
-    if (optionComparer(selectedOptions[0], option)) {
-      return selectedOptions;
+    if (itemComparer(selectedValues[0], item)) {
+      return selectedValues;
     }
 
-    return [option];
+    return [item];
   }
 
-  // The toggled option is selected; remove it from the selection.
-  if (selectedOptions.some((so) => optionComparer(so, option))) {
-    return selectedOptions.filter((so) => !optionComparer(so, option));
+  // The toggled item is selected; remove it from the selection.
+  if (selectedValues.some((sv) => itemComparer(sv, item))) {
+    return selectedValues.filter((sv) => !itemComparer(sv, item));
   }
 
-  // The toggled option is not selected and the selected array is shorter than the limit - add to the selection.
-  if (selectionLimit === null || selectedOptions.length < selectionLimit) {
-    return [...selectedOptions, option];
+  // The toggled item is not selected and the selected array is shorter than the limit - add to the selection.
+  if (selectionLimit === null || selectedValues.length < selectionLimit) {
+    return [...selectedValues, item];
   }
 
   // Truncate the selection to the limit (discard items with lower indexes).
-  const newSelection = selectedOptions.slice(selectedOptions.length - selectionLimit + 1);
-  newSelection.push(option);
+  const newSelection = selectedValues.slice(selectedValues.length - selectionLimit + 1);
+  newSelection.push(item);
 
   return newSelection;
 }
 
-function handleOptionSelection<TOption>(
-  option: TOption,
-  state: ListboxState<TOption>,
-  props: UseListboxParametersWithDefaults<TOption>,
-): ListboxState<TOption> {
-  const {
-    optionComparer = (o, v) => o === v,
-    isOptionDisabled = () => false,
-    selectionLimit,
-  } = props;
+function handleItemSelection<ItemValue>(
+  item: ItemValue,
+  state: ListState<ItemValue>,
+  props: UseListParametersWithDefaults<ItemValue>,
+): ListState<ItemValue> {
+  const { itemComparer = (o, v) => o === v, isItemDisabled = () => false, selectionLimit } = props;
   const { selectedValues } = state;
 
-  const optionIndex = props.options.findIndex((o) => props.optionComparer(option, o));
+  const itemIndex = props.items.findIndex((i) => itemComparer(item, i));
 
-  if (isOptionDisabled(option, optionIndex)) {
+  if (isItemDisabled(item, itemIndex)) {
     return state;
   }
 
-  // if the option is already selected, remove it from the selection, otherwise add it
-  const newSelectedValues = toggleSelection(option, selectedValues, selectionLimit, optionComparer);
+  // if the item is already selected, remove it from the selection, otherwise add it
+  const newSelectedValues = toggleSelection(item, selectedValues, selectionLimit, itemComparer);
 
   return {
     selectedValues: newSelectedValues,
-    highlightedValue: option,
+    highlightedValue: item,
   };
 }
 
-function handleKeyDown<TOption>(
+function handleKeyDown<ItemValue>(
   event: React.KeyboardEvent,
-  state: Readonly<ListboxState<TOption>>,
-  parameters: UseListboxParametersWithDefaults<TOption>,
-): ListboxState<TOption> {
+  state: Readonly<ListState<ItemValue>>,
+  parameters: UseListParametersWithDefaults<ItemValue>,
+): ListState<ItemValue> {
   const previouslySelectedValue = state.highlightedValue;
   const { orientation } = parameters;
 
@@ -296,7 +286,7 @@ function handleKeyDown<TOption>(
         return state;
       }
 
-      return handleOptionSelection(state.highlightedValue, state, parameters);
+      return handleItemSelection(state.highlightedValue, state, parameters);
 
     default:
       break;
@@ -305,10 +295,10 @@ function handleKeyDown<TOption>(
   return state;
 }
 
-function handleBlur<TOption>(
-  state: ListboxState<TOption>,
-  props: UseListboxParametersWithDefaults<TOption>,
-): ListboxState<TOption> {
+function handleBlur<ItemValue>(
+  state: ListState<ItemValue>,
+  props: UseListParametersWithDefaults<ItemValue>,
+): ListState<ItemValue> {
   if (props.focusManagement === 'DOM') {
     return state;
   }
@@ -319,139 +309,138 @@ function handleBlur<TOption>(
   };
 }
 
-const textCriteriaMatches = <TOption>(
-  nextFocus: TOption,
+const textCriteriaMatches = <ItemValue>(
+  nextFocus: ItemValue,
   searchString: string,
-  stringifyOption: (option: TOption) => string | undefined,
+  stringifyItem: (item: ItemValue) => string | undefined,
 ) => {
-  const text = stringifyOption(nextFocus)?.trim().toLowerCase();
+  const text = stringifyItem(nextFocus)?.trim().toLowerCase();
 
   if (!text || text.length === 0) {
-    // Make option not navigable if stringification fails or results in empty string.
+    // Make item not navigable if stringification fails or results in empty string.
     return false;
   }
 
   return text.indexOf(searchString) === 0;
 };
 
-function handleTextNavigation<TOption>(
-  state: ListboxState<TOption>,
+function handleTextNavigation<ItemValue>(
+  state: ListState<ItemValue>,
   searchString: string,
-  props: UseListboxParametersWithDefaults<TOption>,
-): ListboxState<TOption> {
+  props: UseListParametersWithDefaults<ItemValue>,
+): ListState<ItemValue> {
   const {
-    options,
-    isOptionDisabled,
+    items,
+    isItemDisabled,
     disableListWrap,
     disabledItemsFocusable,
-    optionComparer,
-    optionStringifier,
+    itemComparer,
+    itemStringifier,
   } = props;
 
-  const startWithCurrentOption = searchString.length > 1;
+  const startWithCurrentItem = searchString.length > 1;
 
-  let nextOption = startWithCurrentOption
+  let nextItem = startWithCurrentItem
     ? state.highlightedValue
-    : getNewHighlightedOption(
-        options,
+    : getNewHighlightedItem(
+        items,
         state.highlightedValue,
         1,
         disabledItemsFocusable ?? false,
-        isOptionDisabled ?? (() => false),
+        isItemDisabled ?? (() => false),
         disableListWrap ?? false,
-        optionComparer,
+        itemComparer,
       );
 
   // use `for` instead of `while` prevent infinite loop
-  for (let index = 0; index < options.length; index += 1) {
+  for (let index = 0; index < items.length; index += 1) {
     // Return un-mutated state if looped back to the currently highlighted value
-    if (!nextOption || (!startWithCurrentOption && state.highlightedValue === nextOption)) {
+    if (!nextItem || (!startWithCurrentItem && state.highlightedValue === nextItem)) {
       return state;
     }
 
     if (
-      textCriteriaMatches(nextOption, searchString, optionStringifier) &&
-      (!isOptionDisabled(nextOption, options.indexOf(nextOption)) || disabledItemsFocusable)
+      textCriteriaMatches(nextItem, searchString, itemStringifier) &&
+      (!isItemDisabled(nextItem, items.indexOf(nextItem)) || disabledItemsFocusable)
     ) {
-      // The nextOption is the element to be highlighted
+      // The nextItem is the element to be highlighted
       return {
         ...state,
-        highlightedValue: nextOption,
+        highlightedValue: nextItem,
       };
     }
     // Move to the next element.
-    nextOption = getNewHighlightedOption(
-      options,
-      nextOption,
+    nextItem = getNewHighlightedItem(
+      items,
+      nextItem,
       1,
       disabledItemsFocusable ?? false,
-      isOptionDisabled ?? (() => false),
+      isItemDisabled ?? (() => false),
       disableListWrap ?? false,
-      optionComparer,
+      itemComparer,
     );
   }
 
-  // No option match text search criteria
+  // No item matches the text search criteria
   return state;
 }
 
-function handleOptionsChange<TOption>(
-  options: TOption[],
-  previousOptions: TOption[],
-  state: ListboxState<TOption>,
-  props: UseListboxParametersWithDefaults<TOption>,
-): ListboxState<TOption> {
-  const { optionComparer, focusManagement } = props;
+function handleItemsChange<ItemValue>(
+  items: ItemValue[],
+  previousItems: ItemValue[],
+  state: ListState<ItemValue>,
+  props: UseListParametersWithDefaults<ItemValue>,
+): ListState<ItemValue> {
+  const { itemComparer, focusManagement } = props;
 
-  let newHighlightedOption: TOption | null = null;
+  let newHighlightedValue: ItemValue | null = null;
 
   if (state.highlightedValue != null) {
-    newHighlightedOption =
-      options.find((option) => optionComparer(option, state.highlightedValue!)) ?? null;
-  } else if (focusManagement === 'DOM' && previousOptions.length === 0) {
-    // TODO: exclude disabled options
-    newHighlightedOption = options[0] ?? null;
+    newHighlightedValue = items.find((item) => itemComparer(item, state.highlightedValue!)) ?? null;
+  } else if (focusManagement === 'DOM' && previousItems.length === 0) {
+    // TODO: exclude disabled items
+    newHighlightedValue = items[0] ?? null;
   }
 
-  // exclude selected values that are no longer in the options
+  // exclude selected values that are no longer in the items list
   const selectedValues = state.selectedValues ?? [];
   const newSelectedValues = selectedValues.filter((selectedValue) =>
-    options.some((option) => optionComparer(option, selectedValue)),
+    items.some((item) => itemComparer(item, selectedValue)),
   );
 
   return {
-    highlightedValue: newHighlightedOption,
+    highlightedValue: newHighlightedValue,
     selectedValues: newSelectedValues,
   };
 }
 
-export default function defaultListboxReducer<TOption>(
-  state: Readonly<ListboxState<TOption>>,
-  action: ListboxReducerAction<TOption>,
-): Readonly<ListboxState<TOption>> {
+export default function defaultListboxReducer<ItemValue>(
+  state: Readonly<ListState<ItemValue>>,
+  action: ListReducerAction<ItemValue>,
+): Readonly<ListState<ItemValue>> {
   const { type } = action;
 
   switch (type) {
     case ActionTypes.keyDown:
       return handleKeyDown(action.event, state, action.props);
-    case ActionTypes.optionClick:
-      return handleOptionSelection(action.option, state, action.props);
+    case ActionTypes.itemClick:
+      return handleItemSelection(action.item, state, action.props);
     case ActionTypes.blur:
       return handleBlur(state, action.props);
     case ActionTypes.setValue:
       return {
         ...state,
-        selectedValues: action.value,
+        selectedValues: action.values,
       };
     case ActionTypes.setHighlight:
       return {
         ...state,
-        highlightedValue: action.highlight,
+        highlightedValue: action.value,
       };
     case ActionTypes.textNavigation:
       return handleTextNavigation(state, action.searchString, action.props);
-    case ActionTypes.optionsChange:
-      return handleOptionsChange(action.options, action.previousOptions, state, action.props);
+    case ActionTypes.itemsChange:
+      return handleItemsChange(action.items, action.previousItems, state, action.props);
     default:
       return state;
   }
diff --git a/packages/mui-base/src/useListbox/index.ts b/packages/mui-base/src/useListbox/index.ts
index fc75df9d190a10..1d9c6bb86021c9 100644
--- a/packages/mui-base/src/useListbox/index.ts
+++ b/packages/mui-base/src/useListbox/index.ts
@@ -2,8 +2,10 @@ export { default } from './useListbox';
 export * from './useListbox';
 
 export { default as useListItem } from './useListItem';
-export * from './useListItem';
+export * from './useListItem.types';
 
 export * from './useListbox.types';
 
 export { default as defaultListboxReducer } from './defaultListboxReducer';
+
+export * from './actions.types';
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx b/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
index 284ad01db37cc0..f6e4bdd4822c64 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
@@ -2,13 +2,9 @@ import { expect } from 'chai';
 import * as React from 'react';
 import { spy } from 'sinon';
 import { createRenderer } from 'test/utils';
+import { ActionTypes, ListAction } from './actions.types';
+import { ListState, UseListParametersWithDefaults } from './useListbox.types';
 import useControllableReducer from './useControllableReducer';
-import {
-  ActionTypes,
-  ListboxAction,
-  ListboxState,
-  UseListboxParametersWithDefaults,
-} from './useListbox.types';
 
 describe('useControllableReducer', () => {
   const { render } = createRenderer();
@@ -16,19 +12,19 @@ describe('useControllableReducer', () => {
   describe('dispatch', () => {
     it('calls the provided internal reducer', () => {
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const reducer = spy((state: ListboxState<string>, action: ListboxAction<string>) => {
+      const reducer = spy((state: ListState<string>, action: ListAction<string>) => {
         return state;
       });
 
       const actionToDispatch = { type: ActionTypes.setValue as const, value: ['b'], event: null };
-      const props: UseListboxParametersWithDefaults<string> = {
-        options: ['a', 'b', 'c'],
+      const props: UseListParametersWithDefaults<string> = {
+        items: ['a', 'b', 'c'],
         defaultValue: ['a'],
-        isOptionDisabled: () => false,
+        isItemDisabled: () => false,
         disableListWrap: false,
         disabledItemsFocusable: false,
-        optionComparer: (a, b) => a === b,
-        optionStringifier: (option) => option,
+        itemComparer: (a, b) => a === b,
+        itemStringifier: (item) => item,
         orientation: 'vertical',
         selectionLimit: null,
       };
@@ -45,24 +41,24 @@ describe('useControllableReducer', () => {
 
     it('calls the provided external reducer', () => {
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const internalReducer = spy((state: ListboxState<string>, action: ListboxAction<string>) => {
+      const internalReducer = spy((state: ListState<string>, action: ListAction<string>) => {
         return state;
       });
 
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const externalReducer = spy((state: ListboxState<string>, action: ListboxAction<string>) => {
+      const externalReducer = spy((state: ListState<string>, action: ListAction<string>) => {
         return state;
       });
 
       const actionToDispatch = { type: ActionTypes.setValue as const, value: ['b'], event: null };
-      const props: UseListboxParametersWithDefaults<string> = {
-        options: ['a', 'b', 'c'],
+      const props: UseListParametersWithDefaults<string> = {
+        items: ['a', 'b', 'c'],
         defaultValue: ['a'],
-        isOptionDisabled: () => false,
+        isItemDisabled: () => false,
         disableListWrap: false,
         disabledItemsFocusable: false,
-        optionComparer: (a, b) => a === b,
-        optionStringifier: (option) => option,
+        itemComparer: (a, b) => a === b,
+        itemStringifier: (item) => item,
         orientation: 'vertical',
         selectionLimit: null,
       };
@@ -81,7 +77,7 @@ describe('useControllableReducer', () => {
     });
 
     it('calls onChange when the reducer returns a modified selected value', () => {
-      const reducer = spy((state: ListboxState<string>) => {
+      const reducer = spy((state: ListState<string>) => {
         return {
           ...state,
           selectedValues: ['b'],
@@ -96,14 +92,14 @@ describe('useControllableReducer', () => {
       const handleHighlightChange = spy();
 
       function TestComponent() {
-        const props: UseListboxParametersWithDefaults<string> = {
-          options: ['a', 'b', 'c'],
+        const props: UseListParametersWithDefaults<string> = {
+          items: ['a', 'b', 'c'],
           defaultValue: ['a'],
-          isOptionDisabled: () => false,
+          isItemDisabled: () => false,
           disableListWrap: false,
           disabledItemsFocusable: false,
-          optionComparer: (a, b) => a === b,
-          optionStringifier: (option) => option,
+          itemComparer: (a, b) => a === b,
+          itemStringifier: (item) => item,
           onChange: handleChange,
           onHighlightChange: handleHighlightChange,
           orientation: 'vertical',
@@ -123,7 +119,7 @@ describe('useControllableReducer', () => {
     });
 
     it('calls onHighlightChange when the reducer returns a modified highlighted value', () => {
-      const reducer = spy((state: ListboxState<string>) => {
+      const reducer = spy((state: ListState<string>) => {
         return {
           ...state,
           highlightedValue: 'b',
@@ -138,14 +134,14 @@ describe('useControllableReducer', () => {
       const handleHighlightChange = spy();
 
       function TestComponent() {
-        const props: UseListboxParametersWithDefaults<string> = {
-          options: ['a', 'b', 'c'],
+        const props: UseListParametersWithDefaults<string> = {
+          items: ['a', 'b', 'c'],
           defaultValue: ['a'],
-          isOptionDisabled: () => false,
+          isItemDisabled: () => false,
           disableListWrap: false,
           disabledItemsFocusable: false,
-          optionComparer: (a, b) => a === b,
-          optionStringifier: (option) => option,
+          itemComparer: (a, b) => a === b,
+          itemStringifier: (item) => item,
           onChange: handleChange,
           onHighlightChange: handleHighlightChange,
           orientation: 'vertical',
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.ts b/packages/mui-base/src/useListbox/useControllableReducer.ts
index 29ae0f8b3ac9a3..e0b0d16f4023a7 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.ts
+++ b/packages/mui-base/src/useListbox/useControllableReducer.ts
@@ -2,10 +2,10 @@ import * as React from 'react';
 import {
   ActionTypes,
   ListboxAction,
-  ListboxReducer,
-  ListboxReducerAction,
-  ListboxState,
-  UseListboxParametersWithDefaults,
+  ListReducer,
+  ListReducerAction,
+  ListState,
+  UseListParametersWithDefaults,
 } from './useListbox.types';
 import areArraysEqual from '../utils/areArraysEqual';
 
@@ -14,8 +14,8 @@ import areArraysEqual from '../utils/areArraysEqual';
  * the `value` prop is the source of truth instead of the internal state.
  */
 function getControlledState<TOption>(
-  internalState: ListboxState<TOption>,
-  props: UseListboxParametersWithDefaults<TOption>,
+  internalState: ListState<TOption>,
+  props: UseListParametersWithDefaults<TOption>,
 ) {
   if (props.value !== undefined) {
     return { ...internalState, selectedValues: props.value };
@@ -49,9 +49,9 @@ function areOptionsEqual<TOption>(
  * @param lastActionRef The last action that was dispatched.
  */
 function useStateChangeDetection<TOption>(
-  nextState: ListboxState<TOption>,
-  internalPreviousState: ListboxState<TOption>,
-  propsRef: React.RefObject<UseListboxParametersWithDefaults<TOption>>,
+  nextState: ListState<TOption>,
+  internalPreviousState: ListState<TOption>,
+  propsRef: React.RefObject<UseListParametersWithDefaults<TOption>>,
   lastActionRef: React.MutableRefObject<ListboxAction<TOption> | null>,
 ) {
   React.useEffect(() => {
@@ -107,10 +107,10 @@ function useStateChangeDetection<TOption>(
  * @ignore - do not document.
  */
 export default function useControllableReducer<TOption>(
-  internalReducer: ListboxReducer<TOption>,
-  externalReducer: ListboxReducer<TOption> | undefined,
-  props: React.RefObject<UseListboxParametersWithDefaults<TOption>>,
-): [ListboxState<TOption>, (action: ListboxAction<TOption>) => void] {
+  internalReducer: ListReducer<TOption>,
+  externalReducer: ListReducer<TOption> | undefined,
+  props: React.RefObject<UseListParametersWithDefaults<TOption>>,
+): [ListState<TOption>, (action: ListboxAction<TOption>) => void] {
   const { value, defaultValue } = props.current!;
 
   const actionRef = React.useRef<ListboxAction<TOption> | null>(null);
@@ -123,7 +123,7 @@ export default function useControllableReducer<TOption>(
   };
 
   const combinedReducer = React.useCallback(
-    (state: ListboxState<TOption>, action: ListboxReducerAction<TOption>) => {
+    (state: ListState<TOption>, action: ListReducerAction<TOption>) => {
       actionRef.current = action;
 
       if (externalReducer) {
@@ -142,12 +142,12 @@ export default function useControllableReducer<TOption>(
       dispatch({
         props: props.current,
         ...action,
-      } as ListboxReducerAction<TOption>);
+      } as ListReducerAction<TOption>);
     },
     [dispatch, props],
   );
 
-  const previousState = React.useRef<ListboxState<TOption>>(initialState);
+  const previousState = React.useRef<ListState<TOption>>(initialState);
   React.useEffect(() => {
     previousState.current = nextState;
   }, [previousState, nextState]);
diff --git a/packages/mui-base/src/useListbox/useListChangeNotifiers.ts b/packages/mui-base/src/useListbox/useListChangeNotifiers.ts
index 988ac15c28117b..a39b5e9bf8973b 100644
--- a/packages/mui-base/src/useListbox/useListChangeNotifiers.ts
+++ b/packages/mui-base/src/useListbox/useListChangeNotifiers.ts
@@ -4,23 +4,23 @@ import useMessageBus from '../utils/useMessageBus';
 const SELECTION_CHANGE_TOPIC = Symbol('change-selection');
 const HIGHLIGHT_CHANGE_TOPIC = Symbol('change-highlight');
 
-export interface ListChangeNotifiers<TValue> {
+export interface ListChangeNotifiers<ItemValue> {
   /**
    * Calls all the registered selection change handlers.
    *
    * @param newValue - The newly selected value(s).
    */
-  notifySelectionChanged: (newValue: TValue[]) => void;
+  notifySelectionChanged: (newValue: ItemValue[]) => void;
   /**
    * Calls all the registered highlight change handlers.
    *
    * @param newValue - The newly highlighted value.
    */
-  notifyHighlightChanged: (newValue: TValue | null) => void;
+  notifyHighlightChanged: (newValue: ItemValue | null) => void;
 
-  registerSelectionChangeHandler: (handler: (newValue: TValue[]) => void) => () => void;
+  registerSelectionChangeHandler: (handler: (newValue: ItemValue[]) => void) => () => void;
 
-  registerHighlightChangeHandler: (handler: (newValue: TValue | null) => void) => () => void;
+  registerHighlightChangeHandler: (handler: (newValue: ItemValue | null) => void) => () => void;
 }
 
 /**
diff --git a/packages/mui-base/src/useListbox/useListItem.ts b/packages/mui-base/src/useListbox/useListItem.ts
index f549bd326e9c43..0bc7093d804c5d 100644
--- a/packages/mui-base/src/useListbox/useListItem.ts
+++ b/packages/mui-base/src/useListbox/useListItem.ts
@@ -6,13 +6,19 @@ import {
 import { EventHandlers } from '../utils/types';
 import useForcedRerendering from '../utils/useForcedRerendering';
 import { ListContext } from './useListbox';
+import { UseListItemParameters, UseListItemReturnValue } from './useListItem.types';
+import { ActionTypes } from './actions.types';
 
-export interface UseListItemParameters<Item> {
-  item: Item;
-  ref?: React.Ref<HTMLElement>;
-}
-
-export default function useListItem<Item>(parameters: UseListItemParameters<Item>) {
+/**
+ * Contains the logic for an item of a list-like component (e.g. Select, Menu, etc.).
+ * It provides information about the item's state (selected, highlighted) and
+ * handles the item's mouse events.
+ *
+ * @template ItemValue The type of the item's value. This should be consistent with the type of useList's `items` parameter.
+ */
+export default function useListItem<ItemValue>(
+  parameters: UseListItemParameters<ItemValue>,
+): UseListItemReturnValue {
   const { item, ref: externalRef } = parameters;
 
   const itemRef = React.useRef<HTMLElement>(null);
@@ -23,20 +29,15 @@ export default function useListItem<Item>(parameters: UseListItemParameters<Item
     throw new Error('useListItem must be used within a ListProvider');
   }
 
-  const {
-    getItemProps,
-    getItemState,
-    registerHighlightChangeHandler,
-    registerSelectionChangeHandler,
-  } = listContext;
+  const { dispatch, getItemState, registerHighlightChangeHandler, registerSelectionChangeHandler } =
+    listContext;
 
-  const itemState = getItemState(item);
-  const { highlighted, selected } = itemState;
+  const { highlighted, selected, focusable } = getItemState(item);
 
   const rerender = useForcedRerendering();
 
   useEnhancedEffect(() => {
-    function updateHighlightedState(highlightedItem: Item | null) {
+    function updateHighlightedState(highlightedItem: ItemValue | null) {
       if (highlightedItem === item && !highlighted) {
         rerender();
       } else if (highlightedItem !== item && highlighted) {
@@ -48,20 +49,12 @@ export default function useListItem<Item>(parameters: UseListItemParameters<Item
   });
 
   useEnhancedEffect(() => {
-    function updateSelectedState(selectedItems: Item | Item[] | null) {
+    function updateSelectedState(selectedItems: ItemValue[]) {
       if (!selected) {
-        if (Array.isArray(selectedItems)) {
-          if (selectedItems.includes(item)) {
-            rerender();
-          }
-        } else if (selectedItems === item) {
-          rerender();
-        }
-      } else if (Array.isArray(selectedItems)) {
-        if (!selectedItems.includes(item)) {
+        if (selectedItems.includes(item)) {
           rerender();
         }
-      } else if (selectedItems !== item) {
+      } else if (!selectedItems.includes(item)) {
         rerender();
       }
     }
@@ -69,12 +62,60 @@ export default function useListItem<Item>(parameters: UseListItemParameters<Item
     return registerSelectionChangeHandler(updateSelectedState);
   }, [registerSelectionChangeHandler, rerender, selected, item]);
 
+  const createHandleClick = React.useCallback(
+    (other: Record<string, React.EventHandler<any>>) => (event: React.MouseEvent) => {
+      other.onClick?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      event.preventDefault();
+
+      dispatch({
+        type: ActionTypes.itemClick,
+        item,
+        event,
+      });
+    },
+    [dispatch, item],
+  );
+
+  const createHandlePointerOver = React.useCallback(
+    (other: Record<string, React.EventHandler<any>>) => (event: React.PointerEvent) => {
+      other.onMouseOver?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      dispatch({
+        type: ActionTypes.itemHover,
+        item,
+        event,
+      });
+    },
+    [dispatch, item],
+  );
+
+  let tabIndex: number | undefined;
+  if (focusable !== undefined) {
+    tabIndex = focusable ? 0 : -1;
+  }
+
+  const getRootProps = <TOther extends EventHandlers = {}>(
+    otherHandlers: TOther = {} as TOther,
+  ) => ({
+    ...otherHandlers,
+    onClick: createHandleClick(otherHandlers),
+    onPointerOver: createHandlePointerOver(otherHandlers),
+    ref: handleRef,
+    tabIndex,
+    // TODO: id
+  });
+
   return {
-    getItemProps: <TOther extends EventHandlers = {}>(otherHandlers?: TOther) => ({
-      ...getItemProps(item, otherHandlers),
-      ref: handleRef,
-    }),
-    getItemState: () => getItemState(item),
+    getRootProps,
+    highlighted,
     ref: handleRef,
+    selected,
   };
 }
diff --git a/packages/mui-base/src/useListbox/useListItem.types.ts b/packages/mui-base/src/useListbox/useListItem.types.ts
new file mode 100644
index 00000000000000..1d6e152fb37617
--- /dev/null
+++ b/packages/mui-base/src/useListbox/useListItem.types.ts
@@ -0,0 +1,50 @@
+import { EventHandlers } from '../utils';
+
+export interface UseListItemParameters<ItemValue> {
+  /**
+   * The list item.
+   */
+  item: ItemValue;
+  /**
+   * A ref to the list item's DOM element.
+   */
+  ref?: React.Ref<HTMLElement>;
+}
+
+interface UseListItemRootSlotOwnProps {
+  // TODO: ARIA attributes should be added by the higher level component (Select, Menu, etc.)
+  'aria-disabled': React.AriaAttributes['aria-disabled'];
+  'aria-selected': React.AriaAttributes['aria-selected'];
+  id?: string;
+  onClick: React.MouseEventHandler;
+  onPointerOver: React.PointerEventHandler;
+  role: React.AriaRole;
+  tabIndex?: number;
+}
+
+export type UseListItemRootSlotProps<TOther = {}> = Omit<
+  TOther,
+  keyof UseListItemRootSlotOwnProps
+> &
+  UseListItemRootSlotOwnProps;
+
+export interface UseListItemReturnValue {
+  /**
+   * Resolver for the root slot's props.
+   * @param otherHandlers event handlers for the root slot
+   * @returns props that should be spread on the root slot
+   */
+  getRootProps: <TOther extends EventHandlers = {}>() => UseListItemRootSlotProps<TOther>;
+  /**
+   * If `true`, the current item is highlighted.
+   */
+  highlighted: boolean;
+  /**
+   * If `true`, the current item is selected.
+   */
+  selected: boolean;
+  /**
+   * The ref to the root element.
+   */
+  ref: ((instance: HTMLElement | null) => void) | null;
+}
diff --git a/packages/mui-base/src/useListbox/useListbox.test.tsx b/packages/mui-base/src/useListbox/useListbox.test.tsx
index d79e881d49040a..db0b5ecebb8beb 100644
--- a/packages/mui-base/src/useListbox/useListbox.test.tsx
+++ b/packages/mui-base/src/useListbox/useListbox.test.tsx
@@ -2,14 +2,15 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { SinonSpy, spy } from 'sinon';
 import { createRenderer, createEvent, fireEvent } from 'test/utils';
-import useListbox from './useListbox';
+import useListbox, { ListContext } from './useListbox';
+import useListItem from './useListItem';
 
 describe('useListbox', () => {
   const { render } = createRenderer();
   describe('prop: id', () => {
     it('propagates it to the root element', () => {
       function Listbox() {
-        const { getRootProps } = useListbox({ options: [], id: 'test-id' });
+        const { getRootProps } = useListbox({ items: [], id: 'test-id' });
         return <ul {...getRootProps()} />;
       }
       const { getByRole } = render(<Listbox />);
@@ -19,30 +20,38 @@ describe('useListbox', () => {
     });
 
     it('uses the provided id to create option ids', () => {
-      const options = ['one', 'two'];
+      const items = ['one', 'two'];
+
+      function ListItem({ children }: React.PropsWithChildren<{}>) {
+        const id = React.useId();
+        const { getRootProps } = useListItem({ item: id });
+        return <li {...getRootProps()}>{children}</li>;
+      }
+
       function Listbox() {
-        const { getRootProps, getOptionProps } = useListbox({ options, id: 'test-id' });
+        const { getRootProps, contextValue } = useListbox({ items, id: 'test-id' });
         return (
-          <ul {...getRootProps()}>
-            {options.map((o) => (
-              <li key={o} {...getOptionProps(o)}>
-                {o}
-              </li>
-            ))}
-          </ul>
+          <ListContext.Provider value={contextValue}>
+            <ul {...getRootProps()}>
+              {items.map((item) => (
+                <ListItem>{item}</ListItem>
+              ))}
+            </ul>
+          </ListContext.Provider>
         );
       }
+
       const { getAllByRole } = render(<Listbox />);
 
-      const optionElements = getAllByRole('option');
-      optionElements.forEach((opt, index) =>
+      const options = getAllByRole('option');
+      options.forEach((opt, index) =>
         expect(opt).to.have.attribute('id', `test-id-option-${index}`),
       );
     });
 
     it('generates a unique id if not provided explicitly', () => {
       function Listbox() {
-        const { getRootProps } = useListbox({ options: [] });
+        const { getRootProps } = useListbox({ items: [] });
         return <ul {...getRootProps()} />;
       }
 
@@ -62,7 +71,7 @@ describe('useListbox', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown', 'Enter', ' '].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in activeDescendant focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ options: [], focusManagement: 'activeDescendant' });
+          const { getRootProps } = useListbox({ items: [], focusManagement: 'activeDescendant' });
           return <div {...getRootProps()} />;
         }
 
@@ -84,7 +93,7 @@ describe('useListbox', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ options: [], focusManagement: 'DOM' });
+          const { getRootProps } = useListbox({ items: [], focusManagement: 'DOM' });
           return <div {...getRootProps()} />;
         }
 
@@ -106,7 +115,7 @@ describe('useListbox', () => {
     ['Enter', ' '].forEach((key) =>
       it(`does not prevent default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ options: [], focusManagement: 'DOM' });
+          const { getRootProps } = useListbox({ items: [], focusManagement: 'DOM' });
           return <div {...getRootProps()} />;
         }
 
diff --git a/packages/mui-base/src/useListbox/useListbox.ts b/packages/mui-base/src/useListbox/useListbox.ts
index aff34f398da671..2d1fbd61f8b97c 100644
--- a/packages/mui-base/src/useListbox/useListbox.ts
+++ b/packages/mui-base/src/useListbox/useListbox.ts
@@ -1,12 +1,10 @@
 import * as React from 'react';
 import { unstable_useForkRef as useForkRef, unstable_useId as useId } from '@mui/utils';
 import {
-  UseListboxParameters,
-  UseListboxParametersWithDefaults,
-  ActionTypes,
-  OptionState,
-  UseListboxOptionSlotProps,
-  UseListboxRootSlotProps,
+  UseListParameters,
+  UseListParametersWithDefaults,
+  ListItemState,
+  UseListRootSlotProps,
 } from './useListbox.types';
 import defaultReducer from './defaultListboxReducer';
 import useControllableReducer from './useControllableReducer';
@@ -15,21 +13,20 @@ import { EventHandlers } from '../utils/types';
 import useLatest from '../utils/useLatest';
 import useTextNavigation from '../utils/useTextNavigation';
 import useListChangeNotifiers from './useListChangeNotifiers';
-
-const defaultOptionComparer = <TOption>(optionA: TOption, optionB: TOption) => optionA === optionB;
-const defaultIsOptionDisabled = () => false;
-const defaultOptionStringifier = <TOption>(option: TOption) =>
-  typeof option === 'string' ? option : String(option);
-
-export interface ListContextValue<Item> {
-  getItemProps: <TOther extends EventHandlers = {}>(
-    item: Item,
-    otherHandlers?: TOther,
-  ) => UseListboxOptionSlotProps<TOther>;
-  getItemState: (item: Item) => OptionState;
-  registerHighlightChangeHandler: (handler: (item: Item | null) => void) => () => void;
-  registerSelectionChangeHandler: (handler: (items: Item | Item[] | null) => void) => () => void;
-  focusManagement: UseListboxParameters<Item>['focusManagement'];
+import { ActionTypes, ListAction } from './actions.types';
+
+const defaultItemComparer = <ItemValue>(item1: ItemValue, item2: ItemValue) => item1 === item2;
+const defaultIsItemDisabled = () => false;
+const defaultItemStringifier = <ItemValue>(item: ItemValue) =>
+  typeof item === 'string' ? item : String(item);
+
+export interface ListContextValue<ItemValue> {
+  dispatch: (action: ListAction<ItemValue>) => void;
+  getItemState: (item: ItemValue) => ListItemState;
+  registerHighlightChangeHandler: (handler: (item: ItemValue | null) => void) => () => void;
+  registerSelectionChangeHandler: (
+    handler: (items: ItemValue | ItemValue[] | null) => void,
+  ) => () => void;
 }
 
 export const ListContext = React.createContext<ListContextValue<any> | null>(null);
@@ -38,39 +35,40 @@ if (process.env.NODE_ENV !== 'production') {
 }
 
 /**
- * @ignore - internal hook.
+ * The useListbox is a lower-level utility that is used to build list-like components.
+ * It's used to manage the state of the list and its items.
+ *
+ * Supports highlighting a single item and selecting an arbitrary number of items.
  *
- * The useListbox is a lower-level utility that is used to build a listbox component.
- * It's used to manage the state of the listbox and its options.
- * Contains the logic for keyboard navigation, selection, and focus management.
+ * @ignore - internal hook.
  */
-export default function useListbox<TOption>(props: UseListboxParameters<TOption>) {
+export default function useListbox<ItemValue>(params: UseListParameters<ItemValue>) {
   const {
     disabledItemsFocusable = false,
     disableListWrap = false,
     focusManagement = 'activeDescendant',
+    getItemDomElement,
     id: idProp,
-    isOptionDisabled = defaultIsOptionDisabled,
-    listboxRef: externalListboxRef,
+    isItemDisabled = defaultIsItemDisabled,
+    listRef: externalListboxRef,
     onHighlightChange,
-    optionComparer = defaultOptionComparer,
-    optionStringifier = defaultOptionStringifier,
-    options,
-    getOptionElement,
+    itemComparer = defaultItemComparer,
+    items,
+    itemStringifier = defaultItemStringifier,
     orientation = 'vertical',
+    selectionLimit = null,
     stateReducer: externalReducer,
     value: valueParam,
-    selectionLimit = null,
-  } = props;
+  } = params;
 
   const id = useId(idProp);
 
   const defaultIdGenerator = React.useCallback(
-    (_: TOption, index: number) => `${id}-option-${index}`,
+    (_: ItemValue, index: number) => `${id}-option-${index}`,
     [id],
   );
 
-  const optionIdGenerator = props.optionIdGenerator ?? defaultIdGenerator;
+  const itemIdGenerator = params.itemIdGenerator ?? defaultIdGenerator;
 
   const listboxRef = React.useRef<HTMLUListElement>(null);
   const handleRef = useForkRef(externalListboxRef, listboxRef);
@@ -78,7 +76,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   const handleHighlightChange = React.useCallback(
     (
       event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-      value: TOption | null,
+      value: ItemValue | null,
       reason: ActionTypes,
     ) => {
       onHighlightChange?.(event, value, reason);
@@ -86,30 +84,30 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
       if (
         focusManagement === 'DOM' &&
         value != null &&
-        (reason === ActionTypes.optionClick ||
+        (reason === ActionTypes.itemClick ||
           reason === ActionTypes.keyDown ||
           reason === ActionTypes.textNavigation)
       ) {
-        getOptionElement?.(value)?.focus();
+        getItemDomElement?.(value)?.focus();
       }
     },
-    [getOptionElement, onHighlightChange, focusManagement],
+    [getItemDomElement, onHighlightChange, focusManagement],
   );
 
-  const propsWithDefaults: React.RefObject<UseListboxParametersWithDefaults<TOption>> = useLatest(
+  const propsWithDefaults: React.RefObject<UseListParametersWithDefaults<ItemValue>> = useLatest(
     {
-      ...props,
+      ...params,
       disabledItemsFocusable,
       disableListWrap,
       focusManagement,
-      isOptionDisabled,
+      isItemDisabled,
       onHighlightChange: handleHighlightChange,
-      optionComparer,
-      optionStringifier,
+      itemComparer,
+      itemStringifier,
       orientation,
       selectionLimit,
     },
-    [props],
+    [params],
   );
 
   const [{ highlightedValue, selectedValues }, dispatch] = useControllableReducer(
@@ -140,36 +138,35 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   const highlightedIndex = React.useMemo(() => {
     return highlightedValue == null
       ? -1
-      : options.findIndex((option) => optionComparer(option, highlightedValue));
-  }, [highlightedValue, options, optionComparer]);
+      : items.findIndex((item) => itemComparer(item, highlightedValue));
+  }, [highlightedValue, items, itemComparer]);
 
   // introducing refs to avoid recreating the getOptionState function on each change.
   const latestSelectedValues = useLatest(selectedValues);
   const latestHighlightedIndex = useLatest(highlightedIndex);
-  const latestHighlightedValue = useLatest(highlightedValue);
-  const previousOptions = React.useRef<TOption[]>([]);
+  const previousItems = React.useRef<ItemValue[]>([]);
 
   React.useEffect(() => {
-    if (areArraysEqual(previousOptions.current, options, optionComparer)) {
+    if (areArraysEqual(previousItems.current, items, itemComparer)) {
       return;
     }
 
     dispatch({
-      type: ActionTypes.optionsChange,
+      type: ActionTypes.itemsChange,
       event: null,
-      options,
-      previousOptions: previousOptions.current,
+      items,
+      previousItems: previousItems.current,
     });
 
-    previousOptions.current = options;
-  }, [options, optionComparer, dispatch]);
+    previousItems.current = items;
+  }, [items, itemComparer, dispatch]);
 
   const {
     notifySelectionChanged,
     notifyHighlightChanged,
     registerHighlightChangeHandler,
     registerSelectionChangeHandler,
-  } = useListChangeNotifiers<TOption>();
+  } = useListChangeNotifiers<ItemValue>();
 
   React.useEffect(() => {
     notifySelectionChanged(selectedValues);
@@ -180,7 +177,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   }, [highlightedValue, notifyHighlightChanged]);
 
   const setSelectedValue = React.useCallback(
-    (values: TOption[]) => {
+    (values: ItemValue[]) => {
       dispatch({
         type: ActionTypes.setValue,
         event: null,
@@ -191,7 +188,7 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   );
 
   const setHighlightedValue = React.useCallback(
-    (option: TOption | null) => {
+    (option: ItemValue | null) => {
       dispatch({
         type: ActionTypes.setHighlight,
         event: null,
@@ -201,42 +198,6 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     [dispatch],
   );
 
-  const createHandleOptionClick = React.useCallback(
-    (option: TOption, other: Record<string, React.EventHandler<any>>) =>
-      (event: React.MouseEvent) => {
-        other.onClick?.(event);
-        if (event.defaultPrevented) {
-          return;
-        }
-
-        event.preventDefault();
-
-        dispatch({
-          type: ActionTypes.optionClick,
-          option,
-          event,
-        });
-      },
-    [dispatch],
-  );
-
-  const createHandleOptionPointerOver = React.useCallback(
-    (option: TOption, other: Record<string, React.EventHandler<any>>) =>
-      (event: React.PointerEvent) => {
-        other.onMouseOver?.(event);
-        if (event.defaultPrevented) {
-          return;
-        }
-
-        dispatch({
-          type: ActionTypes.optionHover,
-          option,
-          event,
-        });
-      },
-    [dispatch],
-  );
-
   const createHandleKeyDown =
     (other: Record<string, React.EventHandler<any>>) =>
     (event: React.KeyboardEvent<HTMLElement>) => {
@@ -295,12 +256,12 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
 
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
-  ): UseListboxRootSlotProps<TOther> => {
+  ): UseListRootSlotProps<TOther> => {
     return {
       ...otherHandlers,
       'aria-activedescendant':
         focusManagement === 'activeDescendant' && highlightedValue != null
-          ? optionIdGenerator(highlightedValue, highlightedIndex)
+          ? itemIdGenerator(highlightedValue, highlightedIndex)
           : undefined,
       id,
       onBlur: createHandleBlur(otherHandlers),
@@ -311,113 +272,87 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
     };
   };
 
-  const getOptionState = React.useCallback(
-    (option: TOption): OptionState => {
-      const index = options.findIndex((opt) => optionComparer(opt, option));
-      const selected = (latestSelectedValues.current ?? []).some(
-        (value) => value != null && optionComparer(option, value),
-      );
-
-      const disabled = isOptionDisabled(option, index);
-      const highlighted = latestHighlightedIndex.current === index && index !== -1;
-
-      return {
-        disabled,
-        highlighted,
-        index,
-        selected,
-      };
-    },
-    [options, isOptionDisabled, optionComparer, latestSelectedValues, latestHighlightedIndex],
-  );
-
-  const firstFocusableOption = React.useMemo(() => {
+  const firstFocusableItem = React.useMemo(() => {
     if (focusManagement === 'activeDescendant') {
-      // options are not focusable when using activeDescendant
+      // items are not focusable when using activeDescendant
       return undefined;
     }
 
     if (disabledItemsFocusable) {
-      return options[0];
+      return items[0];
     }
 
-    for (let i = 0; i < options.length; i += 1) {
-      const option = options[i];
-      const optionState = getOptionState(option);
-      if (!optionState.disabled) {
-        return option;
+    for (let i = 0; i < items.length; i += 1) {
+      const item = items[i];
+      if (!isItemDisabled(item, i)) {
+        return item;
       }
     }
 
     return undefined;
-  }, [options, disabledItemsFocusable, getOptionState, focusManagement]);
+  }, [items, disabledItemsFocusable, focusManagement, isItemDisabled]);
 
-  const getOptionTabIndex = React.useCallback(
-    (option: TOption, optionState: OptionState) => {
+  const isItemFocusable = React.useCallback(
+    (item: ItemValue, highlighted: boolean, disabled: boolean) => {
       if (focusManagement === 'activeDescendant') {
         return undefined;
       }
 
       // TODO: check if using highlightedValue instead of latestHighlightedValue.current does not kill performance
       if (highlightedValue == null) {
-        return option === firstFocusableOption ? 0 : -1;
+        return item === firstFocusableItem;
       }
 
-      if (!optionState.highlighted) {
-        return -1;
+      if (!highlighted) {
+        return false;
       }
 
-      if (optionState.disabled && !disabledItemsFocusable) {
-        return -1;
+      if (disabled && !disabledItemsFocusable) {
+        return false;
       }
 
-      return 0;
+      return true;
     },
-    [focusManagement, disabledItemsFocusable, firstFocusableOption, highlightedValue],
+    [focusManagement, disabledItemsFocusable, firstFocusableItem, highlightedValue],
   );
 
-  const getOptionProps = React.useCallback(
-    <TOther extends EventHandlers = {}>(
-      option: TOption,
-      otherHandlers: TOther = {} as TOther,
-    ): UseListboxOptionSlotProps<TOther> => {
-      const optionState = getOptionState(option);
+  const getItemState = React.useCallback(
+    (item: ItemValue): ListItemState => {
+      const index = items.findIndex((i) => itemComparer(i, item));
+      const selected = (latestSelectedValues.current ?? []).some(
+        (value) => value != null && itemComparer(item, value),
+      );
+
+      const disabled = isItemDisabled(item, index);
+      const highlighted = latestHighlightedIndex.current === index && index !== -1;
+      const focusable = isItemFocusable(item, highlighted, disabled);
 
       return {
-        ...otherHandlers,
-        'aria-disabled': optionState.disabled || undefined,
-        'aria-selected': optionState.selected,
-        id: optionIdGenerator(option, optionState.index),
-        onClick: createHandleOptionClick(option, otherHandlers),
-        onPointerOver: createHandleOptionPointerOver(option, otherHandlers),
-        role: 'option',
-        tabIndex: getOptionTabIndex(option, optionState),
+        disabled,
+        focusable,
+        highlighted,
+        index,
+        selected,
       };
     },
     [
-      optionIdGenerator,
-      createHandleOptionClick,
-      createHandleOptionPointerOver,
-      getOptionTabIndex,
-      getOptionState,
+      items,
+      isItemDisabled,
+      itemComparer,
+      latestSelectedValues,
+      latestHighlightedIndex,
+      isItemFocusable,
     ],
   );
 
-  const contextValue: ListContextValue<TOption> = React.useMemo(
+  const contextValue: ListContextValue<ItemValue> = React.useMemo(
     () => ({
-      getItemProps: getOptionProps,
-      getItemState: getOptionState,
+      dispatch,
+      getItemState,
       registerHighlightChangeHandler,
       registerSelectionChangeHandler,
-      focusManagement,
     }),
-    [
-      getOptionProps,
-      getOptionState,
-      registerHighlightChangeHandler,
-      registerSelectionChangeHandler,
-      focusManagement,
-    ],
+    [dispatch, getItemState, registerHighlightChangeHandler, registerSelectionChangeHandler],
   );
 
   React.useDebugValue({
@@ -426,13 +361,11 @@ export default function useListbox<TOption>(props: UseListboxParameters<TOption>
   });
 
   return {
+    contextValue,
     getRootProps,
-    getOptionProps,
-    getOptionState,
     highlightedOption: highlightedValue,
     selectedOptions: selectedValues,
-    setSelectedValue,
     setHighlightedValue,
-    contextValue,
+    setSelectedValue,
   };
 }
diff --git a/packages/mui-base/src/useListbox/useListbox.types.ts b/packages/mui-base/src/useListbox/useListbox.types.ts
index b339e54375b628..80c4947b353bcc 100644
--- a/packages/mui-base/src/useListbox/useListbox.types.ts
+++ b/packages/mui-base/src/useListbox/useListbox.types.ts
@@ -1,121 +1,44 @@
 import * as React from 'react';
+import { ActionTypes, ListAction } from './actions.types';
 
-type UseListboxStrictParametersRequiredKeys =
-  | 'isOptionDisabled'
+type UseListStrictParametersRequiredKeys =
+  | 'isItemDisabled'
   | 'disableListWrap'
   | 'disabledItemsFocusable'
-  | 'optionComparer'
+  | 'itemComparer'
   | 'orientation'
-  | 'optionStringifier'
+  | 'itemStringifier'
   | 'selectionLimit';
 
-export type UseListboxParametersWithDefaults<TOption> = Omit<
-  UseListboxParameters<TOption>,
-  UseListboxStrictParametersRequiredKeys
+export type UseListParametersWithDefaults<ItemValue> = Omit<
+  UseListParameters<ItemValue>,
+  UseListStrictParametersRequiredKeys
 > &
-  Required<Pick<UseListboxParameters<TOption>, UseListboxStrictParametersRequiredKeys>>;
+  Required<Pick<UseListParameters<ItemValue>, UseListStrictParametersRequiredKeys>>;
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
 
-enum ActionTypes {
-  blur = 'blur',
-  focus = 'focus',
-  keyDown = 'keyDown',
-  optionClick = 'optionClick',
-  optionHover = 'optionHover',
-  optionsChange = 'optionsChange',
-  setValue = 'setValue',
-  setHighlight = 'setHighlight',
-  textNavigation = 'textNagivation',
-}
-
-// split declaration and export due to https://github.com/codesandbox/codesandbox-client/issues/6435
-export { ActionTypes };
-
-interface OptionClickAction<TOption> {
-  type: ActionTypes.optionClick;
-  option: TOption;
-  event: React.MouseEvent;
-}
-
-interface OptionHoverAction<TOption> {
-  type: ActionTypes.optionHover;
-  option: TOption;
-  event: React.MouseEvent;
-}
-
-interface FocusAction {
-  type: ActionTypes.focus;
-  event: React.FocusEvent;
-}
-
-interface BlurAction {
-  type: ActionTypes.blur;
-  event: React.FocusEvent;
-}
-
-interface KeyDownAction {
-  type: ActionTypes.keyDown;
-  event: React.KeyboardEvent;
-}
-
-interface SetValueAction<TOption> {
-  type: ActionTypes.setValue;
-  event: null;
-  value: TOption[];
-}
-
-interface SetHighlightAction<TOption> {
-  type: ActionTypes.setHighlight;
-  event: null;
-  highlight: TOption | null;
-}
-
-interface TextNavigationAction {
-  type: ActionTypes.textNavigation;
-  event: React.KeyboardEvent;
-  searchString: string;
-}
-
-interface OptionsChangeAction<TOption> {
-  type: ActionTypes.optionsChange;
-  event: null;
-  options: TOption[];
-  previousOptions: TOption[];
-}
-
-export type ListboxAction<TOption> =
-  | OptionClickAction<TOption>
-  | OptionHoverAction<TOption>
-  | FocusAction
-  | BlurAction
-  | KeyDownAction
-  | SetHighlightAction<TOption>
-  | TextNavigationAction
-  | SetValueAction<TOption>
-  | OptionsChangeAction<TOption>;
-
-export type ListboxReducerAction<T> = ListboxAction<T> & {
-  props: UseListboxParametersWithDefaults<T>;
+export type ListReducerAction<T> = ListAction<T> & {
+  props: UseListParametersWithDefaults<T>;
 };
 
-export interface ListboxState<TOption> {
-  highlightedValue: TOption | null;
-  selectedValues: TOption[];
+export interface ListState<ItemValue> {
+  highlightedValue: ItemValue | null;
+  selectedValues: ItemValue[];
 }
 
-export type ListboxReducer<TOption> = (
-  state: ListboxState<TOption>,
-  action: ListboxReducerAction<TOption>,
-) => ListboxState<TOption>;
+export type ListReducer<ItemValue> = (
+  state: ListState<ItemValue>,
+  action: ListReducerAction<ItemValue>,
+) => ListState<ItemValue>;
 
-export interface UseListboxParameters<TOption> {
+export interface UseListParameters<ItemValue> {
   /**
-   * The default selected value. Use when the listbox is not controlled.
+   * The default selected value. Use when the list component is not controlled.
    */
-  defaultValue?: TOption[];
+  defaultValue?: ItemValue[];
   /**
-   * If `true`, it will be possible to highlight disabled options.
+   * If `true`, it will be possible to highlight disabled items.
    * @default false
    */
   disabledItemsFocusable?: boolean;
@@ -126,87 +49,96 @@ export interface UseListboxParameters<TOption> {
   disableListWrap?: boolean;
   focusManagement?: FocusManagementType;
   /**
-   * A function that returns the DOM element associated with an option.
+   * A function that returns the DOM element associated with an item.
+   * This is required to set focus when using the `DOM` focus management.
    *
-   * @param option Option to get the DOM element for.
+   * @param item List item to get the DOM element for.
    */
-  getOptionElement?: (option: TOption) => HTMLElement | null;
+  getItemDomElement?: (itemValue: ItemValue) => HTMLElement | null;
   /**
-   * Id attribute of the listbox.
+   * Id attribute of the list component.
    */
   id?: string;
   /**
-   * A function that determines if a particular option is disabled.
+   * A function that determines if a particular item is disabled.
    * @default () => false
    */
-  isOptionDisabled?: (option: TOption, index: number) => boolean;
+  isItemDisabled?: (itemValue: ItemValue, index: number) => boolean;
   /**
-   * Ref of the listbox DOM element.
+   * Ref of the list root DOM element.
    */
-  listboxRef?: React.Ref<any>;
+  listRef?: React.Ref<any>;
   /**
-   * Callback fired when the value changes.
+   * Callback fired when the selected value changes.
    */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    value: TOption[],
+    values: ItemValue[],
     reason: ActionTypes,
   ) => void;
   /**
-   * Callback fired when the highlighted option changes.
+   * Callback fired when the highlighted item changes.
+   * The `value` is null if there is no highlighted item.
    */
   onHighlightChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    option: TOption | null,
+    value: ItemValue | null,
     reason: ActionTypes,
   ) => void;
   /**
-   * A function that tests equality between two options.
+   * A function that tests equality between two items' values.
    * @default (a, b) => a === b
    */
-  optionComparer?: (optionA: TOption, optionB: TOption) => boolean;
+  itemComparer?: (itemValue1: ItemValue, itemValue2: ItemValue) => boolean;
   /**
    * A function that generates the id attribute of individual options.
    */
-  optionIdGenerator?: (option: TOption, index: number) => string;
+  itemIdGenerator?: (value: ItemValue, index: number) => string;
   /**
    * A function that converts an object to its string representation
    * @default (o) => o
    */
-  optionStringifier?: (option: TOption) => string | undefined;
+  itemStringifier?: (option: ItemValue) => string | undefined;
   /**
-   * Array of options to be rendered in the list.
+   * Array of list items.
    */
-  options: TOption[];
+  items: ItemValue[];
   /**
-   * Orientation of the items in the listbox.
+   * Orientation of the items in the list.
    * Determines the actions that are performed when arrow keys are pressed.
    */
   orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
   /**
-   * Maximum number of options that can be selected at once.
+   * Maximum number of items that can be selected at once.
    * Set to `null` to disable the limit.
+   *
+   * @default null
    */
   selectionLimit?: number | null;
   /**
-   * Custom state reducer function. It calculates the new state (highlighted and selected options)
+   * Custom state reducer function. It calculates the new state (highlighted and selected items)
    * based on the previous one and the performed action.
    */
-  stateReducer?: ListboxReducer<TOption>;
+  stateReducer?: ListReducer<ItemValue>;
   /**
-   * The selected value. Use when the listbox is controlled.
+   * The selected value. Use when the list component is controlled.
    */
-  value?: TOption[];
+  value?: ItemValue[];
 }
 
-export interface OptionState {
+export interface ListItemState {
   disabled: boolean;
+  /**
+   * Determines if the item is focusable.
+   * If `undefined`, focusing doesn't apply as focusManagement is set to 'activeDescendant'.
+   */
+  focusable: boolean | undefined;
   highlighted: boolean;
   index: number;
   selected: boolean;
 }
 
-interface UseListboxRootSlotOwnProps {
+interface UseListRootSlotOwnProps {
   'aria-activedescendant'?: React.AriaAttributes['aria-activedescendant'];
   id?: string;
   onBlur: React.FocusEventHandler;
@@ -216,20 +148,4 @@ interface UseListboxRootSlotOwnProps {
   ref: React.Ref<any>;
 }
 
-export type UseListboxRootSlotProps<TOther = {}> = TOther & UseListboxRootSlotOwnProps;
-
-interface UseListboxOptionSlotOwnProps {
-  'aria-disabled': React.AriaAttributes['aria-disabled'];
-  'aria-selected': React.AriaAttributes['aria-selected'];
-  id?: string;
-  onClick: React.MouseEventHandler;
-  onPointerOver: React.PointerEventHandler;
-  role: React.AriaRole;
-  tabIndex?: number;
-}
-
-export type UseListboxOptionSlotProps<TOther = {}> = Omit<
-  TOther,
-  keyof UseListboxOptionSlotOwnProps
-> &
-  UseListboxOptionSlotOwnProps;
+export type UseListRootSlotProps<TOther = {}> = TOther & UseListRootSlotOwnProps;
diff --git a/packages/mui-joy/src/Option/OptionProps.ts b/packages/mui-joy/src/Option/OptionProps.ts
index fc3ac4f051e7b0..42c81703eb805a 100644
--- a/packages/mui-joy/src/Option/OptionProps.ts
+++ b/packages/mui-joy/src/Option/OptionProps.ts
@@ -5,7 +5,7 @@ import {
   OverridableTypeMap,
   OverrideProps,
 } from '@mui/types';
-import { OptionState } from '@mui/base/useListbox';
+import { ListItemState } from '@mui/base/useListbox';
 import { ColorPaletteProp, VariantProp, SxProps, ApplyColorInversion } from '../styles/types';
 
 export type OptionSlot = 'root';
@@ -66,7 +66,7 @@ export type OptionProps<
 
 export interface OptionOwnerState
   extends ApplyColorInversion<Omit<OptionProps, 'disabled'>>,
-    OptionState {}
+    ListItemState {}
 
 export type ExtendOption<M extends OverridableTypeMap> = ((
   props: OverrideProps<ExtendOptionTypeMap<M>, 'a'>,

From ec17fdd8569b31013659a26eb2ca43841fff603f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 17 Mar 2023 11:49:55 +0100
Subject: [PATCH 05/49] Rename useListbox to useList

---
 docs/pages/experiments/base/listbox.tsx       | 17 +++++-----
 packages/mui-base/src/index.d.ts              |  3 --
 packages/mui-base/src/index.js                |  3 --
 .../mui-base/src/useButton/useButton.types.ts |  2 +-
 .../{useListbox => useList}/actions.types.ts  |  0
 .../defaultListboxReducer.test.ts             |  2 +-
 .../defaultListboxReducer.ts                  |  2 +-
 .../src/{useListbox => useList}/index.ts      |  7 ++--
 .../useControllableReducer.test.tsx           |  2 +-
 .../useControllableReducer.ts                 | 19 ++++++-----
 .../useList.test.tsx}                         | 14 ++++----
 .../useListbox.ts => useList/useList.ts}      | 19 +++++------
 .../useList.types.ts}                         |  0
 .../useListChangeNotifiers.ts                 |  0
 .../{useListbox => useList}/useListItem.ts    |  2 +-
 .../useListItem.types.ts                      |  4 ++-
 packages/mui-base/src/useTab/useTab.ts        |  9 +++---
 packages/mui-base/src/useTabs/useTabs.ts      |  4 +--
 .../src/useTabsList/TabsListProvider.tsx      | 11 +++----
 .../mui-base/src/useTabsList/useTabsList.ts   | 32 +++++++++----------
 .../src/useTabsList/useTabsList.types.ts      |  6 ++--
 packages/mui-base/src/utils/useCompound.ts    |  4 +++
 .../mui-base/src/utils/useTextNavigation.ts   |  2 +-
 packages/mui-joy/src/Option/OptionProps.ts    |  2 +-
 24 files changed, 80 insertions(+), 86 deletions(-)
 rename packages/mui-base/src/{useListbox => useList}/actions.types.ts (100%)
 rename packages/mui-base/src/{useListbox => useList}/defaultListboxReducer.test.ts (99%)
 rename packages/mui-base/src/{useListbox => useList}/defaultListboxReducer.ts (99%)
 rename packages/mui-base/src/{useListbox => useList}/index.ts (65%)
 rename packages/mui-base/src/{useListbox => useList}/useControllableReducer.test.tsx (99%)
 rename packages/mui-base/src/{useListbox => useList}/useControllableReducer.ts (90%)
 rename packages/mui-base/src/{useListbox/useListbox.test.tsx => useList/useList.test.tsx} (87%)
 rename packages/mui-base/src/{useListbox/useListbox.ts => useList/useList.ts} (94%)
 rename packages/mui-base/src/{useListbox/useListbox.types.ts => useList/useList.types.ts} (100%)
 rename packages/mui-base/src/{useListbox => useList}/useListChangeNotifiers.ts (100%)
 rename packages/mui-base/src/{useListbox => useList}/useListItem.ts (98%)
 rename packages/mui-base/src/{useListbox => useList}/useListItem.types.ts (91%)

diff --git a/docs/pages/experiments/base/listbox.tsx b/docs/pages/experiments/base/listbox.tsx
index 1ea7e10fbd0374..36f8526f9dcc1a 100644
--- a/docs/pages/experiments/base/listbox.tsx
+++ b/docs/pages/experiments/base/listbox.tsx
@@ -1,7 +1,7 @@
 /* eslint-disable react/no-danger */
 import * as React from 'react';
 import clsx from 'clsx';
-import useListbox, { ListContext, useListItem } from '@mui/base/useListbox';
+import useList, { ListContext, useListItem } from '@mui/base/useList';
 
 const styles = `
   body {
@@ -93,14 +93,13 @@ const Item = React.forwardRef(function Item(
   ref: React.Ref<HTMLElement>,
 ) {
   const item = props.value;
-  const { getItemProps, getItemState } = useListItem({ item, ref });
+  const { getRootProps, selected, highlighted } = useListItem({ item, ref });
 
-  const itemProps = getItemProps();
-  const state = getItemState();
+  const itemProps = getRootProps();
 
   const classes = clsx('item', {
-    highlighted: state.highlighted,
-    selected: state.selected,
+    highlighted,
+    selected,
   });
 
   return (
@@ -132,9 +131,9 @@ function List() {
   }
 
   const itemRefs = React.useRef(new Map<number, HTMLElement>());
-  const listbox = useListbox({
-    options: items,
-    getOptionElement: (item) => itemRefs.current.get(item) || null,
+  const listbox = useList({
+    items,
+    getItemDomElement: (item) => itemRefs.current.get(item) || null,
     orientation,
     focusManagement,
     selectionLimit: 1,
diff --git a/packages/mui-base/src/index.d.ts b/packages/mui-base/src/index.d.ts
index c77372e6d90674..451930cca019f2 100644
--- a/packages/mui-base/src/index.d.ts
+++ b/packages/mui-base/src/index.d.ts
@@ -86,9 +86,6 @@ export * from './useButton';
 export { default as useInput } from './useInput';
 export * from './useInput';
 
-export { default as useListbox } from './useListbox';
-export * from './useListbox';
-
 export { default as useMenu } from './useMenu';
 export * from './useMenu';
 
diff --git a/packages/mui-base/src/index.js b/packages/mui-base/src/index.js
index c11b9f3834e2ac..f78c30b8701fee 100644
--- a/packages/mui-base/src/index.js
+++ b/packages/mui-base/src/index.js
@@ -80,9 +80,6 @@ export * from './useButton';
 export { default as useInput } from './useInput';
 export * from './useInput';
 
-export { default as useListbox } from './useListbox';
-export * from './useListbox';
-
 export { default as useMenu } from './useMenu';
 export * from './useMenu';
 
diff --git a/packages/mui-base/src/useButton/useButton.types.ts b/packages/mui-base/src/useButton/useButton.types.ts
index c492df913b7d64..dbb5dc7dfea83c 100644
--- a/packages/mui-base/src/useButton/useButton.types.ts
+++ b/packages/mui-base/src/useButton/useButton.types.ts
@@ -70,7 +70,7 @@ export interface UseButtonReturnValue {
    */
   active: boolean;
   /**
-   * A ref to the component's root element.
+   * A ref to the component's root DOM element.
    */
   ref: ((instance: unknown) => void) | null;
 }
diff --git a/packages/mui-base/src/useListbox/actions.types.ts b/packages/mui-base/src/useList/actions.types.ts
similarity index 100%
rename from packages/mui-base/src/useListbox/actions.types.ts
rename to packages/mui-base/src/useList/actions.types.ts
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
similarity index 99%
rename from packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
rename to packages/mui-base/src/useList/defaultListboxReducer.test.ts
index 505e780d238eed..222d1c718df852 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { expect } from 'chai';
-import { ListReducerAction, ListState } from './useListbox.types';
+import { ListReducerAction, ListState } from './useList.types';
 import { ActionTypes } from './actions.types';
 import defaultReducer from './defaultListboxReducer';
 
diff --git a/packages/mui-base/src/useListbox/defaultListboxReducer.ts b/packages/mui-base/src/useList/defaultListboxReducer.ts
similarity index 99%
rename from packages/mui-base/src/useListbox/defaultListboxReducer.ts
rename to packages/mui-base/src/useList/defaultListboxReducer.ts
index 8e42ec0f94d667..280cc230729ef3 100644
--- a/packages/mui-base/src/useListbox/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { ActionTypes } from './actions.types';
-import { ListState, UseListParametersWithDefaults, ListReducerAction } from './useListbox.types';
+import { ListState, UseListParametersWithDefaults, ListReducerAction } from './useList.types';
 
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
diff --git a/packages/mui-base/src/useListbox/index.ts b/packages/mui-base/src/useList/index.ts
similarity index 65%
rename from packages/mui-base/src/useListbox/index.ts
rename to packages/mui-base/src/useList/index.ts
index 1d9c6bb86021c9..0a0c22633334cc 100644
--- a/packages/mui-base/src/useListbox/index.ts
+++ b/packages/mui-base/src/useList/index.ts
@@ -1,11 +1,10 @@
-export { default } from './useListbox';
-export * from './useListbox';
+export { default } from './useList';
+export * from './useList';
+export * from './useList.types';
 
 export { default as useListItem } from './useListItem';
 export * from './useListItem.types';
 
-export * from './useListbox.types';
-
 export { default as defaultListboxReducer } from './defaultListboxReducer';
 
 export * from './actions.types';
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx b/packages/mui-base/src/useList/useControllableReducer.test.tsx
similarity index 99%
rename from packages/mui-base/src/useListbox/useControllableReducer.test.tsx
rename to packages/mui-base/src/useList/useControllableReducer.test.tsx
index f6e4bdd4822c64..f4098a668000f1 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/useList/useControllableReducer.test.tsx
@@ -3,7 +3,7 @@ import * as React from 'react';
 import { spy } from 'sinon';
 import { createRenderer } from 'test/utils';
 import { ActionTypes, ListAction } from './actions.types';
-import { ListState, UseListParametersWithDefaults } from './useListbox.types';
+import { ListState, UseListParametersWithDefaults } from './useList.types';
 import useControllableReducer from './useControllableReducer';
 
 describe('useControllableReducer', () => {
diff --git a/packages/mui-base/src/useListbox/useControllableReducer.ts b/packages/mui-base/src/useList/useControllableReducer.ts
similarity index 90%
rename from packages/mui-base/src/useListbox/useControllableReducer.ts
rename to packages/mui-base/src/useList/useControllableReducer.ts
index e0b0d16f4023a7..e74d8613728700 100644
--- a/packages/mui-base/src/useListbox/useControllableReducer.ts
+++ b/packages/mui-base/src/useList/useControllableReducer.ts
@@ -1,13 +1,12 @@
 import * as React from 'react';
 import {
-  ActionTypes,
-  ListboxAction,
   ListReducer,
   ListReducerAction,
   ListState,
   UseListParametersWithDefaults,
-} from './useListbox.types';
+} from './useList.types';
 import areArraysEqual from '../utils/areArraysEqual';
+import { ActionTypes, ListAction } from './actions.types';
 
 /**
  * Gets the current state. If the selectedValue is controlled,
@@ -52,7 +51,7 @@ function useStateChangeDetection<TOption>(
   nextState: ListState<TOption>,
   internalPreviousState: ListState<TOption>,
   propsRef: React.RefObject<UseListParametersWithDefaults<TOption>>,
-  lastActionRef: React.MutableRefObject<ListboxAction<TOption> | null>,
+  lastActionRef: React.MutableRefObject<ListAction<TOption> | null>,
 ) {
   React.useEffect(() => {
     if (!propsRef.current || lastActionRef.current === null) {
@@ -69,12 +68,12 @@ function useStateChangeDetection<TOption>(
     }
 
     const previousState = getControlledState(internalPreviousState, propsRef.current);
-    const { optionComparer, onChange } = propsRef.current;
+    const { itemComparer, onChange } = propsRef.current;
 
     const previousSelectedValues = previousState?.selectedValues ?? [];
     const nextSelectedValues = nextState.selectedValues as TOption[];
 
-    if (!areArraysEqual(nextSelectedValues, previousSelectedValues, optionComparer)) {
+    if (!areArraysEqual(nextSelectedValues, previousSelectedValues, itemComparer)) {
       onChange?.(lastActionRef.current.event, nextSelectedValues, lastActionRef.current.type);
     }
 
@@ -83,7 +82,7 @@ function useStateChangeDetection<TOption>(
       !areOptionsEqual(
         internalPreviousState.highlightedValue,
         nextState.highlightedValue,
-        propsRef.current.optionComparer,
+        propsRef.current.itemComparer,
       )
     ) {
       propsRef.current?.onHighlightChange?.(
@@ -110,10 +109,10 @@ export default function useControllableReducer<TOption>(
   internalReducer: ListReducer<TOption>,
   externalReducer: ListReducer<TOption> | undefined,
   props: React.RefObject<UseListParametersWithDefaults<TOption>>,
-): [ListState<TOption>, (action: ListboxAction<TOption>) => void] {
+): [ListState<TOption>, (action: ListAction<TOption>) => void] {
   const { value, defaultValue } = props.current!;
 
-  const actionRef = React.useRef<ListboxAction<TOption> | null>(null);
+  const actionRef = React.useRef<ListAction<TOption> | null>(null);
 
   const initialSelectedValues = (value === undefined ? defaultValue : value) ?? [];
 
@@ -138,7 +137,7 @@ export default function useControllableReducer<TOption>(
   const [nextState, dispatch] = React.useReducer(combinedReducer, initialState);
 
   const dispatchWithProps = React.useCallback(
-    (action: ListboxAction<TOption>) => {
+    (action: ListAction<TOption>) => {
       dispatch({
         props: props.current,
         ...action,
diff --git a/packages/mui-base/src/useListbox/useListbox.test.tsx b/packages/mui-base/src/useList/useList.test.tsx
similarity index 87%
rename from packages/mui-base/src/useListbox/useListbox.test.tsx
rename to packages/mui-base/src/useList/useList.test.tsx
index db0b5ecebb8beb..3ea184a220ecf7 100644
--- a/packages/mui-base/src/useListbox/useListbox.test.tsx
+++ b/packages/mui-base/src/useList/useList.test.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { SinonSpy, spy } from 'sinon';
 import { createRenderer, createEvent, fireEvent } from 'test/utils';
-import useListbox, { ListContext } from './useListbox';
+import useList, { ListContext } from './useList';
 import useListItem from './useListItem';
 
 describe('useListbox', () => {
@@ -10,7 +10,7 @@ describe('useListbox', () => {
   describe('prop: id', () => {
     it('propagates it to the root element', () => {
       function Listbox() {
-        const { getRootProps } = useListbox({ items: [], id: 'test-id' });
+        const { getRootProps } = useList({ items: [], id: 'test-id' });
         return <ul {...getRootProps()} />;
       }
       const { getByRole } = render(<Listbox />);
@@ -29,7 +29,7 @@ describe('useListbox', () => {
       }
 
       function Listbox() {
-        const { getRootProps, contextValue } = useListbox({ items, id: 'test-id' });
+        const { getRootProps, contextValue } = useList({ items, id: 'test-id' });
         return (
           <ListContext.Provider value={contextValue}>
             <ul {...getRootProps()}>
@@ -51,7 +51,7 @@ describe('useListbox', () => {
 
     it('generates a unique id if not provided explicitly', () => {
       function Listbox() {
-        const { getRootProps } = useListbox({ items: [] });
+        const { getRootProps } = useList({ items: [] });
         return <ul {...getRootProps()} />;
       }
 
@@ -71,7 +71,7 @@ describe('useListbox', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown', 'Enter', ' '].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in activeDescendant focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ items: [], focusManagement: 'activeDescendant' });
+          const { getRootProps } = useList({ items: [], focusManagement: 'activeDescendant' });
           return <div {...getRootProps()} />;
         }
 
@@ -93,7 +93,7 @@ describe('useListbox', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ items: [], focusManagement: 'DOM' });
+          const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
           return <div {...getRootProps()} />;
         }
 
@@ -115,7 +115,7 @@ describe('useListbox', () => {
     ['Enter', ' '].forEach((key) =>
       it(`does not prevent default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useListbox({ items: [], focusManagement: 'DOM' });
+          const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
           return <div {...getRootProps()} />;
         }
 
diff --git a/packages/mui-base/src/useListbox/useListbox.ts b/packages/mui-base/src/useList/useList.ts
similarity index 94%
rename from packages/mui-base/src/useListbox/useListbox.ts
rename to packages/mui-base/src/useList/useList.ts
index 2d1fbd61f8b97c..b36fd40a55ee85 100644
--- a/packages/mui-base/src/useListbox/useListbox.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -5,7 +5,7 @@ import {
   UseListParametersWithDefaults,
   ListItemState,
   UseListRootSlotProps,
-} from './useListbox.types';
+} from './useList.types';
 import defaultReducer from './defaultListboxReducer';
 import useControllableReducer from './useControllableReducer';
 import areArraysEqual from '../utils/areArraysEqual';
@@ -35,14 +35,14 @@ if (process.env.NODE_ENV !== 'production') {
 }
 
 /**
- * The useListbox is a lower-level utility that is used to build list-like components.
+ * The useList is a lower-level utility that is used to build list-like components.
  * It's used to manage the state of the list and its items.
  *
  * Supports highlighting a single item and selecting an arbitrary number of items.
  *
  * @ignore - internal hook.
  */
-export default function useListbox<ItemValue>(params: UseListParameters<ItemValue>) {
+export default function useList<ItemValue>(params: UseListParameters<ItemValue>) {
   const {
     disabledItemsFocusable = false,
     disableListWrap = false,
@@ -50,7 +50,7 @@ export default function useListbox<ItemValue>(params: UseListParameters<ItemValu
     getItemDomElement,
     id: idProp,
     isItemDisabled = defaultIsItemDisabled,
-    listRef: externalListboxRef,
+    listRef: externalListRef,
     onHighlightChange,
     itemComparer = defaultItemComparer,
     items,
@@ -70,8 +70,8 @@ export default function useListbox<ItemValue>(params: UseListParameters<ItemValu
 
   const itemIdGenerator = params.itemIdGenerator ?? defaultIdGenerator;
 
-  const listboxRef = React.useRef<HTMLUListElement>(null);
-  const handleRef = useForkRef(externalListboxRef, listboxRef);
+  const listRef = React.useRef<HTMLUListElement>(null);
+  const handleRef = useForkRef(externalListRef, listRef);
 
   const handleHighlightChange = React.useCallback(
     (
@@ -217,7 +217,7 @@ export default function useListbox<ItemValue>(params: UseListParameters<ItemValu
 
       if (focusManagement === 'activeDescendant') {
         // When the child element is focused using the activeDescendant attribute,
-        // the listbox handles keyboard events on its behalf.
+        // the list handles keyboard events on its behalf.
         // We have to `preventDefault()` is this case to prevent the browser from
         // scrolling the view when space is pressed or submitting forms when enter is pressed.
         keysToPreventDefault.push(' ', 'Enter');
@@ -243,8 +243,8 @@ export default function useListbox<ItemValue>(params: UseListParameters<ItemValu
         return;
       }
 
-      if (listboxRef.current?.contains(event.relatedTarget)) {
-        // focus remains within the listbox
+      if (listRef.current?.contains(event.relatedTarget)) {
+        // focus remains within the list
         return;
       }
 
@@ -266,6 +266,7 @@ export default function useListbox<ItemValue>(params: UseListParameters<ItemValu
       id,
       onBlur: createHandleBlur(otherHandlers),
       onKeyDown: createHandleKeyDown(otherHandlers),
+      // TODO: role should be set by a downstream component
       role: 'listbox',
       tabIndex: focusManagement === 'DOM' ? -1 : 0,
       ref: handleRef,
diff --git a/packages/mui-base/src/useListbox/useListbox.types.ts b/packages/mui-base/src/useList/useList.types.ts
similarity index 100%
rename from packages/mui-base/src/useListbox/useListbox.types.ts
rename to packages/mui-base/src/useList/useList.types.ts
diff --git a/packages/mui-base/src/useListbox/useListChangeNotifiers.ts b/packages/mui-base/src/useList/useListChangeNotifiers.ts
similarity index 100%
rename from packages/mui-base/src/useListbox/useListChangeNotifiers.ts
rename to packages/mui-base/src/useList/useListChangeNotifiers.ts
diff --git a/packages/mui-base/src/useListbox/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
similarity index 98%
rename from packages/mui-base/src/useListbox/useListItem.ts
rename to packages/mui-base/src/useList/useListItem.ts
index 0bc7093d804c5d..cdd3432cad2d7c 100644
--- a/packages/mui-base/src/useListbox/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -5,7 +5,7 @@ import {
 } from '@mui/utils';
 import { EventHandlers } from '../utils/types';
 import useForcedRerendering from '../utils/useForcedRerendering';
-import { ListContext } from './useListbox';
+import { ListContext } from './useList';
 import { UseListItemParameters, UseListItemReturnValue } from './useListItem.types';
 import { ActionTypes } from './actions.types';
 
diff --git a/packages/mui-base/src/useListbox/useListItem.types.ts b/packages/mui-base/src/useList/useListItem.types.ts
similarity index 91%
rename from packages/mui-base/src/useListbox/useListItem.types.ts
rename to packages/mui-base/src/useList/useListItem.types.ts
index 1d6e152fb37617..756199ab413881 100644
--- a/packages/mui-base/src/useListbox/useListItem.types.ts
+++ b/packages/mui-base/src/useList/useListItem.types.ts
@@ -34,7 +34,9 @@ export interface UseListItemReturnValue {
    * @param otherHandlers event handlers for the root slot
    * @returns props that should be spread on the root slot
    */
-  getRootProps: <TOther extends EventHandlers = {}>() => UseListItemRootSlotProps<TOther>;
+  getRootProps: <TOther extends EventHandlers = {}>(
+    otherHandlers?: TOther,
+  ) => UseListItemRootSlotProps<TOther>;
   /**
    * If `true`, the current item is highlighted.
    */
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index 881301d8ec19d8..d4d109a64956f9 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -4,7 +4,7 @@ import { useTabContext } from '../TabsUnstyled';
 import { UseTabParameters, UseTabReturnValue, UseTabRootSlotProps } from './useTab.types';
 import { EventHandlers } from '../utils';
 import { useCompoundItem } from '../utils/useCompound';
-import { useListItem } from '../useListbox';
+import { useListItem } from '../useList';
 import useButton from '../useButton';
 import { TabMetadata } from '../useTabs';
 /**
@@ -25,9 +25,10 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
   const { value: selectedValue, idPrefix = '', selectionFollowsFocus } = useTabContext();
 
   const {
-    getItemProps: getTabProps,
-    getItemState: getTabState,
+    getRootProps: getTabProps,
     ref: listItemRefHandler,
+    highlighted,
+    selected,
   } = useListItem({
     item: value,
   });
@@ -53,8 +54,6 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
     tabMetadata,
   );
 
-  const { selected, highlighted } = getTabState();
-
   const getRootProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabRootSlotProps<TOther> => {
diff --git a/packages/mui-base/src/useTabs/useTabs.ts b/packages/mui-base/src/useTabs/useTabs.ts
index de3091963a5798..186e43ea84a27d 100644
--- a/packages/mui-base/src/useTabs/useTabs.ts
+++ b/packages/mui-base/src/useTabs/useTabs.ts
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { unstable_useControlled as useControlled, unstable_useId as useId } from '@mui/utils';
 import { UseTabsParameters, UseTabsReturnValue } from './useTabs.types';
-import useCompoundParent from '../utils/useCompound';
+import { useCompoundParent } from '../utils/useCompound';
 
 export interface TabMetadata {
   disabled: boolean;
@@ -45,7 +45,7 @@ function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
     [onChange, setValue],
   );
 
-  const { subitems: tabPanels, ...compoundComponentContextValue } = useCompoundParent<
+  const { subitems: tabPanels, contextValue: compoundComponentContextValue } = useCompoundParent<
     string | number,
     string
   >();
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index c8be55662fbbd6..68daabd4eba13a 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { ListContext, ListContextValue } from '../useListbox';
+import { ListContext, ListContextValue } from '../useList';
 import { TabMetadata } from '../useTabs/useTabs';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 
@@ -17,9 +17,8 @@ export interface TabsListProviderProps {
 export default function TabsListProvider(props: TabsListProviderProps) {
   const { value, children } = props;
   const {
-    focusManagement,
+    dispatch,
     getItemIndex,
-    getItemProps,
     getItemState,
     registerHighlightChangeHandler,
     registerSelectionChangeHandler,
@@ -30,17 +29,15 @@ export default function TabsListProvider(props: TabsListProviderProps) {
 
   const listContextValue: ListContextValue<string | number> = React.useMemo(
     () => ({
-      focusManagement,
-      getItemProps,
+      dispatch,
       getItemState,
       getItemIndex,
       registerHighlightChangeHandler,
       registerSelectionChangeHandler,
     }),
     [
-      focusManagement,
+      dispatch,
       getItemIndex,
-      getItemProps,
       getItemState,
       registerHighlightChangeHandler,
       registerSelectionChangeHandler,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 156d469ebba4af..34391d4788eaaa 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -9,12 +9,12 @@ import {
 import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
-import useListbox, {
+import useList, {
   ActionTypes,
   defaultListboxReducer,
-  ListboxReducer,
-  UseListboxParameters,
-} from '../useListbox';
+  ListReducer,
+  UseListParameters,
+} from '../useList';
 
 export const TabsListContext = React.createContext<TabsListContextValue | null>(null);
 
@@ -60,28 +60,28 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
 
   const isRtl = direction === 'rtl';
 
-  let listOrientation: UseListboxParameters<any>['orientation'];
+  let listOrientation: UseListParameters<any>['orientation'];
   if (orientation === 'vertical') {
     listOrientation = 'vertical';
   } else {
     listOrientation = isRtl ? 'horizontal-rtl' : 'horizontal-ltr';
   }
 
-  const stateReducer: ListboxReducer<string | number> = React.useCallback(
+  const stateReducer: ListReducer<string | number> = React.useCallback(
     (state, action) => {
       const newState = defaultListboxReducer(state, action);
 
-      if (action.type === ActionTypes.optionsChange) {
+      if (action.type === ActionTypes.itemsChange) {
         return {
           ...newState,
           highlightedValue: newState.selectedValues[0] ?? null,
         };
       }
 
-      if (action.type === ActionTypes.setValue && action.value != null) {
+      if (action.type === ActionTypes.setValue && action.values != null) {
         return {
           ...newState,
-          highlightedValue: action.value[0],
+          highlightedValue: action.values[0],
         };
       }
 
@@ -107,14 +107,14 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
 
   const handleChange = React.useCallback(
     (
-      e:
+      event:
         | React.FocusEvent<Element, Element>
         | React.KeyboardEvent<Element>
         | React.MouseEvent<Element, MouseEvent>
         | null,
       newValue: (string | number)[],
     ) => {
-      onSelected(e, newValue[0] ?? null);
+      onSelected(event, newValue[0] ?? null);
     },
     [onSelected],
   );
@@ -124,14 +124,14 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     selectedOptions,
     highlightedOption,
     contextValue: listContextValue,
-  } = useListbox({
+  } = useList({
     disabledItemsFocusable: !selectionFollowsFocus,
     focusManagement: 'DOM',
-    getOptionElement: getTabElement,
-    isOptionDisabled: (option) => subitems.get(option)?.disabled ?? false,
-    listboxRef: externalRef,
+    getItemDomElement: getTabElement,
+    isItemDisabled: (item) => subitems.get(item)?.disabled ?? false,
+    items: subitemKeys,
+    listRef: externalRef,
     onChange: handleChange,
-    options: subitemKeys,
     orientation: listOrientation,
     selectionLimit: 1,
     stateReducer,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.types.ts b/packages/mui-base/src/useTabsList/useTabsList.types.ts
index 009ee6734a6d9c..37e5678b34c925 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.types.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.types.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { OptionState, UseListboxOptionSlotProps } from '../useListbox';
+import { ListItemState, UseListItemRootSlotProps } from '../useList';
 import { EventHandlers } from '../utils';
 import { TabsListProviderValue } from './TabsListProvider';
 
@@ -7,8 +7,8 @@ export interface TabsListContextValue {
   getTabProps: <TOther extends EventHandlers = {}>(
     tabValue: string | number,
     otherHandlers?: TOther,
-  ) => UseListboxOptionSlotProps;
-  getTabState: (tabValue: string | number) => OptionState;
+  ) => UseListItemRootSlotProps;
+  getTabState: (tabValue: string | number) => ListItemState;
 }
 
 export interface UseTabsListParameters {
diff --git a/packages/mui-base/src/utils/useCompound.ts b/packages/mui-base/src/utils/useCompound.ts
index 0534f0644c70b6..3d7350f16b78a7 100644
--- a/packages/mui-base/src/utils/useCompound.ts
+++ b/packages/mui-base/src/utils/useCompound.ts
@@ -36,6 +36,8 @@ export interface UseCompoundParentReturnValue<Key, Subitem> {
  * directly inside the parent component. They can be anywhere in the tree (and even rendered by other components).
  *
  * The downside is that this doesn't work with SSR as it relies on the useEffect hook.
+ *
+ * @ignore - internal hook.
  */
 export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<Key, Subitem> {
   const [subitems, setSubitems] = React.useState(new Map<Key, Subitem>());
@@ -90,6 +92,8 @@ export interface UseCompoundItemReturnValue {
  *
  * @param id A unique key for the child component
  * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
+ *
+ * @ignore - internal hook.
  */
 export function useCompoundItem<Key, Subitem>(
   id: Key,
diff --git a/packages/mui-base/src/utils/useTextNavigation.ts b/packages/mui-base/src/utils/useTextNavigation.ts
index 92b8c159768ab0..105945f8996f24 100644
--- a/packages/mui-base/src/utils/useTextNavigation.ts
+++ b/packages/mui-base/src/utils/useTextNavigation.ts
@@ -6,7 +6,7 @@ const TEXT_NAVIGATION_RESET_TIMEOUT = 500; // milliseconds
  * @ignore - internal hook.
  *
  * Provides a handler for text navigation.
- * It's used to navigate the listbox by typing the first letters of the options.
+ * It's used to navigate a list by typing the first letters of the options.
  *
  * @param callback A function to be called when the navigation should be performed.
  * @returns A function to be used in a keydown event handler.
diff --git a/packages/mui-joy/src/Option/OptionProps.ts b/packages/mui-joy/src/Option/OptionProps.ts
index 42c81703eb805a..d425f84f870437 100644
--- a/packages/mui-joy/src/Option/OptionProps.ts
+++ b/packages/mui-joy/src/Option/OptionProps.ts
@@ -5,7 +5,7 @@ import {
   OverridableTypeMap,
   OverrideProps,
 } from '@mui/types';
-import { ListItemState } from '@mui/base/useListbox';
+import { ListItemState } from '@mui/base/useList';
 import { ColorPaletteProp, VariantProp, SxProps, ApplyColorInversion } from '../styles/types';
 
 export type OptionSlot = 'root';

From 56c64161fd301811187f2f52736d0dafec2e06a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 17 Mar 2023 21:08:39 +0100
Subject: [PATCH 06/49] Use the new building blocks in MenuUnstyled

---
 .../MenuItemUnstyled.test.tsx                 |  21 +--
 .../MenuItemUnstyled.types.ts                 |   7 -
 .../src/MenuUnstyled/MenuUnstyled.tsx         |   4 +-
 .../src/MenuUnstyled/MenuUnstyledContext.ts   |  19 ---
 packages/mui-base/src/MenuUnstyled/index.tsx  |   3 -
 .../MenuUnstyled/useMenuChangeNotifiers.ts    |  43 ------
 .../src/TabUnstyled/TabUnstyled.test.tsx      |  13 +-
 .../useList/useControllableReducer.test.tsx   |   4 +-
 .../mui-base/src/useList/useList.test.tsx     |  24 +--
 packages/mui-base/src/useList/useList.ts      |  10 +-
 .../mui-base/src/useList/useList.types.ts     |   1 -
 .../mui-base/src/useList/useListItem.types.ts |   4 -
 .../mui-base/src/useMenu/MenuProvider.tsx     |  61 ++++++++
 packages/mui-base/src/useMenu/index.ts        |   1 +
 packages/mui-base/src/useMenu/useMenu.ts      | 138 +++++++-----------
 .../mui-base/src/useMenu/useMenu.types.ts     |  12 +-
 .../mui-base/src/useMenuItem/useMenuItem.ts   | 130 +++++++----------
 .../src/useMenuItem/useMenuItem.types.ts      |  23 ++-
 packages/mui-base/src/useTab/useTab.ts        |   1 +
 packages/mui-base/src/utils/useCompound.ts    |  10 +-
 20 files changed, 242 insertions(+), 287 deletions(-)
 delete mode 100644 packages/mui-base/src/MenuUnstyled/MenuUnstyledContext.ts
 delete mode 100644 packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
 create mode 100644 packages/mui-base/src/useMenu/MenuProvider.tsx

diff --git a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
index a0523173cf4e1a..29083c5f96f074 100644
--- a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
+++ b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
@@ -1,22 +1,27 @@
 import * as React from 'react';
 import { createMount, createRenderer, describeConformanceUnstyled } from 'test/utils';
 import MenuItemUnstyled, { menuItemUnstyledClasses } from '@mui/base/MenuItemUnstyled';
-import { MenuUnstyledContext } from '@mui/base/MenuUnstyled';
+import { MenuProvider } from '@mui/base/useMenu';
 
 const dummyGetItemState = () => ({
   disabled: false,
   highlighted: false,
   selected: false,
   index: 0,
+  focusable: true,
 });
 
 const testContext = {
-  getItemState: dummyGetItemState,
+  dispatch: () => {},
+  getItemIndex: () => 0,
   getItemProps: () => ({}),
-  registerItem: () => {},
-  unregisterItem: () => {},
+  getItemState: dummyGetItemState,
   open: false,
   registerHighlightChangeHandler: () => () => {},
+  registerItem: () => {},
+  registerSelectionChangeHandler: () => () => {},
+  totalSubitemCount: 0,
+  unregisterItem: () => {},
 };
 
 describe('<MenuItemUnstyled />', () => {
@@ -26,14 +31,10 @@ describe('<MenuItemUnstyled />', () => {
   describeConformanceUnstyled(<MenuItemUnstyled />, () => ({
     inheritComponent: 'li',
     render: (node) => {
-      return render(
-        <MenuUnstyledContext.Provider value={testContext}>{node}</MenuUnstyledContext.Provider>,
-      );
+      return render(<MenuProvider value={testContext}>{node}</MenuProvider>);
     },
     mount: (node: React.ReactNode) => {
-      const wrapper = mount(
-        <MenuUnstyledContext.Provider value={testContext}>{node}</MenuUnstyledContext.Provider>,
-      );
+      const wrapper = mount(<MenuProvider value={testContext}>{node}</MenuProvider>);
       return wrapper.childAt(0);
     },
     refInstanceof: window.HTMLLIElement,
diff --git a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.types.ts b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.types.ts
index 2778f91491daed..ddaeae6637d98a 100644
--- a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.types.ts
+++ b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.types.ts
@@ -62,13 +62,6 @@ export type MenuItemUnstyledProps<
   component?: D;
 };
 
-export interface MenuItemMetadata {
-  id: string;
-  disabled: boolean;
-  label?: string;
-  ref: React.RefObject<HTMLElement>;
-}
-
 export interface MenuItemState {
   disabled: boolean;
   highlighted: boolean;
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
index 36dfab2a844886..7c453a9c97d501 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
@@ -2,7 +2,6 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { HTMLElementType, refType } from '@mui/utils';
 import { OverridableComponent } from '@mui/types';
-import MenuUnstyledContext from './MenuUnstyledContext';
 import {
   MenuUnstyledOwnerState,
   MenuUnstyledProps,
@@ -15,6 +14,7 @@ import composeClasses from '../composeClasses';
 import PopperUnstyled from '../PopperUnstyled';
 import useSlotProps from '../utils/useSlotProps';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
+import MenuProvider from '../useMenu/MenuProvider';
 
 function useUtilityClasses(ownerState: MenuUnstyledOwnerState) {
   const { open } = ownerState;
@@ -102,7 +102,7 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
   return (
     <Root {...rootProps}>
       <Listbox {...listboxProps}>
-        <MenuUnstyledContext.Provider value={contextValue}>{children}</MenuUnstyledContext.Provider>
+        <MenuProvider value={contextValue}>{children}</MenuProvider>
       </Listbox>
     </Root>
   );
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyledContext.ts b/packages/mui-base/src/MenuUnstyled/MenuUnstyledContext.ts
deleted file mode 100644
index 118dd908f06524..00000000000000
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyledContext.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import * as React from 'react';
-import { MenuItemMetadata, MenuItemState } from '../MenuItemUnstyled/MenuItemUnstyled.types';
-
-export interface MenuUnstyledContextType {
-  registerItem: (id: string, metadata: MenuItemMetadata) => void;
-  unregisterItem: (id: string) => void;
-  getItemState: (id: string) => MenuItemState | undefined;
-  getItemProps: (
-    id: string,
-    otherHandlers?: Record<string, React.EventHandler<any>>,
-  ) => Record<string, any>;
-  open: boolean;
-  registerHighlightChangeHandler: (handler: (itemId: string | null) => void) => void;
-}
-
-const MenuUnstyledContext = React.createContext<MenuUnstyledContextType | null>(null);
-MenuUnstyledContext.displayName = 'MenuUnstyledContext';
-
-export default MenuUnstyledContext;
diff --git a/packages/mui-base/src/MenuUnstyled/index.tsx b/packages/mui-base/src/MenuUnstyled/index.tsx
index 1d1d80240d78a4..cdf84f55254728 100644
--- a/packages/mui-base/src/MenuUnstyled/index.tsx
+++ b/packages/mui-base/src/MenuUnstyled/index.tsx
@@ -1,8 +1,5 @@
 export { default } from './MenuUnstyled';
 
-export { default as MenuUnstyledContext } from './MenuUnstyledContext';
-export * from './MenuUnstyledContext';
-
 export { default as menuUnstyledClasses } from './menuUnstyledClasses';
 export * from './menuUnstyledClasses';
 
diff --git a/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts b/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
deleted file mode 100644
index fe4b8c5e090c0e..00000000000000
--- a/packages/mui-base/src/MenuUnstyled/useMenuChangeNotifiers.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import * as React from 'react';
-import useMessageBus from '../utils/useMessageBus';
-
-const HIGHLIGHT_CHANGE_TOPIC = Symbol('menu:change-highlight');
-
-export interface MenuChangeNotifiers {
-  /**
-   * Calls all the registered highlight change handlers.
-   *
-   * @param newValue - The newly highlighted value.
-   */
-  notifyHighlightChanged: (newValue: string | null) => void;
-
-  registerHighlightChangeHandler: (handler: (newValue: string | null) => void) => () => void;
-}
-
-/**
- * @ignore - internal hook.
- *
- * This hook is used to notify any interested components about changes in the Menu's selection and highlight.
- */
-export default function useMenuChangeNotifiers(): MenuChangeNotifiers {
-  const messageBus = useMessageBus();
-
-  const notifyHighlightChanged = React.useCallback(
-    (newValue: string | null) => {
-      messageBus.publish(HIGHLIGHT_CHANGE_TOPIC, newValue);
-    },
-    [messageBus],
-  );
-
-  const registerHighlightChangeHandler = React.useCallback(
-    (handler: (newValue: string | null) => void) => {
-      return messageBus.subscribe(HIGHLIGHT_CHANGE_TOPIC, handler);
-    },
-    [messageBus],
-  );
-
-  return {
-    notifyHighlightChanged,
-    registerHighlightChangeHandler,
-  };
-}
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
index d5c7c3958eb152..c6c6b2852610d6 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
@@ -9,25 +9,16 @@ describe('<TabUnstyled />', () => {
   const { render } = createRenderer();
 
   const testTabsListContext: TabsListProviderValue = {
+    dispatch: () => {},
     registerItem: () => {},
     unregisterItem: () => {},
     getItemIndex: () => 0,
     totalSubitemCount: 1,
-    getItemProps() {
-      return {
-        'aria-disabled': undefined,
-        'aria-selected': undefined,
-        onClick: () => {},
-        onPointerOver: () => {},
-        role: 'tab' as const,
-      } as any;
-    },
     getItemState() {
-      return { disabled: false, highlighted: false, selected: false, index: 0 };
+      return { disabled: false, highlighted: false, selected: false, focusable: true, index: 0 };
     },
     registerHighlightChangeHandler: () => () => {},
     registerSelectionChangeHandler: () => () => {},
-    focusManagement: 'DOM',
   };
 
   describeConformanceUnstyled(<TabUnstyled value="1" />, () => ({
diff --git a/packages/mui-base/src/useList/useControllableReducer.test.tsx b/packages/mui-base/src/useList/useControllableReducer.test.tsx
index f4098a668000f1..90682917a4aa2c 100644
--- a/packages/mui-base/src/useList/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/useList/useControllableReducer.test.tsx
@@ -16,7 +16,7 @@ describe('useControllableReducer', () => {
         return state;
       });
 
-      const actionToDispatch = { type: ActionTypes.setValue as const, value: ['b'], event: null };
+      const actionToDispatch = { type: ActionTypes.setValue as const, values: ['b'], event: null };
       const props: UseListParametersWithDefaults<string> = {
         items: ['a', 'b', 'c'],
         defaultValue: ['a'],
@@ -50,7 +50,7 @@ describe('useControllableReducer', () => {
         return state;
       });
 
-      const actionToDispatch = { type: ActionTypes.setValue as const, value: ['b'], event: null };
+      const actionToDispatch = { type: ActionTypes.setValue as const, values: ['b'], event: null };
       const props: UseListParametersWithDefaults<string> = {
         items: ['a', 'b', 'c'],
         defaultValue: ['a'],
diff --git a/packages/mui-base/src/useList/useList.test.tsx b/packages/mui-base/src/useList/useList.test.tsx
index 3ea184a220ecf7..c6af0ec1e5d44f 100644
--- a/packages/mui-base/src/useList/useList.test.tsx
+++ b/packages/mui-base/src/useList/useList.test.tsx
@@ -5,13 +5,13 @@ import { createRenderer, createEvent, fireEvent } from 'test/utils';
 import useList, { ListContext } from './useList';
 import useListItem from './useListItem';
 
-describe('useListbox', () => {
+describe('useList', () => {
   const { render } = createRenderer();
   describe('prop: id', () => {
     it('propagates it to the root element', () => {
       function Listbox() {
         const { getRootProps } = useList({ items: [], id: 'test-id' });
-        return <ul {...getRootProps()} />;
+        return <ul role="listbox" {...getRootProps()} />;
       }
       const { getByRole } = render(<Listbox />);
 
@@ -24,17 +24,21 @@ describe('useListbox', () => {
 
       function ListItem({ children }: React.PropsWithChildren<{}>) {
         const id = React.useId();
-        const { getRootProps } = useListItem({ item: id });
-        return <li {...getRootProps()}>{children}</li>;
+        const { getRootProps, selected } = useListItem({ item: id });
+        return (
+          <li role="option" aria-selected={selected} {...getRootProps()}>
+            {children}
+          </li>
+        );
       }
 
       function Listbox() {
         const { getRootProps, contextValue } = useList({ items, id: 'test-id' });
         return (
           <ListContext.Provider value={contextValue}>
-            <ul {...getRootProps()}>
+            <ul role="listbox" {...getRootProps()}>
               {items.map((item) => (
-                <ListItem>{item}</ListItem>
+                <ListItem key={item}>{item}</ListItem>
               ))}
             </ul>
           </ListContext.Provider>
@@ -52,7 +56,7 @@ describe('useListbox', () => {
     it('generates a unique id if not provided explicitly', () => {
       function Listbox() {
         const { getRootProps } = useList({ items: [] });
-        return <ul {...getRootProps()} />;
+        return <ul role="listbox" {...getRootProps()} />;
       }
 
       const { getAllByRole } = render(
@@ -72,7 +76,7 @@ describe('useListbox', () => {
       it(`prevents default behavior when ${key} is pressed in activeDescendant focus management mode`, () => {
         function Listbox() {
           const { getRootProps } = useList({ items: [], focusManagement: 'activeDescendant' });
-          return <div {...getRootProps()} />;
+          return <div role="listbox" {...getRootProps()} />;
         }
 
         const { getByRole } = render(<Listbox />);
@@ -94,7 +98,7 @@ describe('useListbox', () => {
       it(`prevents default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
           const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
-          return <div {...getRootProps()} />;
+          return <div role="listbox" {...getRootProps()} />;
         }
 
         const { getByRole } = render(<Listbox />);
@@ -116,7 +120,7 @@ describe('useListbox', () => {
       it(`does not prevent default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
           const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
-          return <div {...getRootProps()} />;
+          return <div role="listbox" {...getRootProps()} />;
         }
 
         const { getByRole } = render(<Listbox />);
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index b36fd40a55ee85..0a59c4867021bb 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -130,7 +130,7 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
       dispatch({
         type: ActionTypes.setValue,
         event: null,
-        value: valueParam,
+        values: valueParam,
       });
     }
   }, [valueParam, selectedValues, dispatch]);
@@ -181,18 +181,18 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
       dispatch({
         type: ActionTypes.setValue,
         event: null,
-        value: values,
+        values,
       });
     },
     [dispatch],
   );
 
   const setHighlightedValue = React.useCallback(
-    (option: ItemValue | null) => {
+    (item: ItemValue | null) => {
       dispatch({
         type: ActionTypes.setHighlight,
         event: null,
-        highlight: option,
+        value: item,
       });
     },
     [dispatch],
@@ -266,8 +266,6 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
       id,
       onBlur: createHandleBlur(otherHandlers),
       onKeyDown: createHandleKeyDown(otherHandlers),
-      // TODO: role should be set by a downstream component
-      role: 'listbox',
       tabIndex: focusManagement === 'DOM' ? -1 : 0,
       ref: handleRef,
     };
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 80c4947b353bcc..6501d64da26125 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -143,7 +143,6 @@ interface UseListRootSlotOwnProps {
   id?: string;
   onBlur: React.FocusEventHandler;
   onKeyDown: React.KeyboardEventHandler;
-  role: React.AriaRole;
   tabIndex: number;
   ref: React.Ref<any>;
 }
diff --git a/packages/mui-base/src/useList/useListItem.types.ts b/packages/mui-base/src/useList/useListItem.types.ts
index 756199ab413881..23ce56b6dc0aa3 100644
--- a/packages/mui-base/src/useList/useListItem.types.ts
+++ b/packages/mui-base/src/useList/useListItem.types.ts
@@ -12,13 +12,9 @@ export interface UseListItemParameters<ItemValue> {
 }
 
 interface UseListItemRootSlotOwnProps {
-  // TODO: ARIA attributes should be added by the higher level component (Select, Menu, etc.)
-  'aria-disabled': React.AriaAttributes['aria-disabled'];
-  'aria-selected': React.AriaAttributes['aria-selected'];
   id?: string;
   onClick: React.MouseEventHandler;
   onPointerOver: React.PointerEventHandler;
-  role: React.AriaRole;
   tabIndex?: number;
 }
 
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
new file mode 100644
index 00000000000000..509dccbac956a2
--- /dev/null
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { MenuItemMetadata } from '../useMenuItem';
+import { ListContext, ListContextValue } from '../useList';
+import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+
+export type MenuProviderValue = CompoundComponentContextValue<string, MenuItemMetadata> &
+  ListContextValue<string>;
+
+export interface MenuProviderProps {
+  value: MenuProviderValue;
+  children: React.ReactNode;
+}
+
+export default function MenuProvider(props: MenuProviderProps) {
+  const { value, children } = props;
+
+  const {
+    dispatch,
+    getItemIndex,
+    getItemState,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+    registerItem,
+    unregisterItem,
+    totalSubitemCount,
+  } = value;
+
+  const listContextValue: ListContextValue<string> = React.useMemo(
+    () => ({
+      dispatch,
+      getItemState,
+      getItemIndex,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    }),
+    [
+      dispatch,
+      getItemIndex,
+      getItemState,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    ],
+  );
+
+  const compoundComponentContextValue: CompoundComponentContextValue<string, MenuItemMetadata> =
+    React.useMemo(
+      () => ({
+        getItemIndex,
+        registerItem,
+        totalSubitemCount,
+        unregisterItem,
+      }),
+      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+    );
+
+  return (
+    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
+      <ListContext.Provider value={listContextValue}>{children}</ListContext.Provider>
+    </CompoundComponentContext.Provider>
+  );
+}
diff --git a/packages/mui-base/src/useMenu/index.ts b/packages/mui-base/src/useMenu/index.ts
index e3343bd18553ca..fafe3ff6f6647e 100644
--- a/packages/mui-base/src/useMenu/index.ts
+++ b/packages/mui-base/src/useMenu/index.ts
@@ -1,2 +1,3 @@
 export { default } from './useMenu';
 export * from './useMenu.types';
+export { default as MenuProvider } from './MenuProvider';
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 3161c0a568a3f8..69b5919a0ce49d 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -1,24 +1,23 @@
 import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
-import useListbox, {
+import useList, {
   defaultListboxReducer,
-  ListboxState,
+  ListState,
   ActionTypes,
-  ListboxReducerAction,
-} from '../useListbox';
+  ListReducerAction,
+} from '../useList';
 import { UseMenuListboxSlotProps, UseMenuParameters, UseMenuReturnValue } from './useMenu.types';
 import { EventHandlers } from '../utils';
-import useMenuChangeNotifiers from '../MenuUnstyled/useMenuChangeNotifiers';
-import type { MenuUnstyledContextType } from '../MenuUnstyled';
-import { MenuItemMetadata, MenuItemState } from '../MenuItemUnstyled/MenuItemUnstyled.types';
+import { useCompoundParent } from '../utils/useCompound';
+import { MenuItemMetadata } from '../useMenuItem';
 
 function stateReducer(
-  state: ListboxState<string>,
-  action: ListboxReducerAction<string>,
-): ListboxState<string> {
+  state: ListState<string>,
+  action: ListReducerAction<string>,
+): ListState<string> {
   if (
     action.type === ActionTypes.blur ||
-    action.type === ActionTypes.optionHover ||
+    action.type === ActionTypes.itemHover ||
     action.type === ActionTypes.setValue
   ) {
     return state;
@@ -29,11 +28,11 @@ function stateReducer(
   if (
     action.type !== ActionTypes.setHighlight &&
     newState.highlightedValue === null &&
-    action.props.options.length > 0
+    action.props.items.length > 0
   ) {
     return {
       ...newState,
-      highlightedValue: action.props.options[0],
+      highlightedValue: action.props.items[0],
     };
   }
 
@@ -52,68 +51,65 @@ function stateReducer(
 export default function useMenu(parameters: UseMenuParameters = {}): UseMenuReturnValue {
   const { listboxRef: listboxRefProp, open = false, onClose, listboxId } = parameters;
 
-  const [menuItems, setMenuItems] = React.useState<Record<string, MenuItemMetadata>>({});
-
   const listboxRef = React.useRef<HTMLElement | null>(null);
   const handleRef = useForkRef(listboxRef, listboxRefProp);
 
-  const registerItem = React.useCallback((id: string, metadata: MenuItemMetadata) => {
-    setMenuItems((previousState) => {
-      const newState = { ...previousState };
-      newState[id] = metadata;
-      return newState;
-    });
-  }, []);
+  const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
+    string,
+    MenuItemMetadata
+  >();
 
-  const unregisterItem = React.useCallback((id: string) => {
-    setMenuItems((previousState) => {
-      const newState = { ...previousState };
-      delete newState[id];
-      return newState;
-    });
-  }, []);
+  const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
 
-  const { notifyHighlightChanged, registerHighlightChangeHandler } = useMenuChangeNotifiers();
+  const getItemDomElement = React.useCallback(
+    (itemId: string) => {
+      if (itemId == null) {
+        return null;
+      }
+
+      return subitems.get(itemId)?.ref.current ?? null;
+    },
+    [subitems],
+  );
 
   const {
-    getOptionState,
-    getOptionProps,
     getRootProps,
     highlightedOption,
     setHighlightedValue: setListboxHighlight,
-  } = useListbox({
-    options: Object.keys(menuItems),
-    optionStringifier: (id: string) => menuItems[id].label || menuItems[id].ref.current?.innerText,
-    isOptionDisabled: (id) => menuItems?.[id]?.disabled || false,
-    listboxRef: handleRef,
+    contextValue: listContextValue,
+  } = useList({
+    disabledItemsFocusable: true,
     focusManagement: 'DOM',
+    getItemDomElement,
     id: listboxId,
-    stateReducer,
+    isItemDisabled: (id) => subitems?.get(id)?.disabled || false,
+    items: subitemKeys,
+    itemStringifier: (id: string) =>
+      subitems.get(id)?.label || subitems.get(id)?.ref.current?.innerText,
+    listRef: handleRef,
     selectionLimit: 0,
-    disabledItemsFocusable: true,
+    stateReducer,
   });
 
-  React.useEffect(() => {
-    notifyHighlightChanged(highlightedOption);
-  }, [highlightedOption, notifyHighlightChanged]);
-
   const highlightFirstItem = React.useCallback(() => {
-    if (Object.keys(menuItems).length > 0) {
-      setListboxHighlight(menuItems[Object.keys(menuItems)[0]].id);
+    if (subitems.size > 0) {
+      setListboxHighlight(subitems.get(Array.from(subitems.keys())[0])!.id);
     }
-  }, [menuItems, setListboxHighlight]);
+  }, [subitems, setListboxHighlight]);
 
   const highlightLastItem = React.useCallback(() => {
-    if (Object.keys(menuItems).length > 0) {
-      setListboxHighlight(menuItems[Object.keys(menuItems)[Object.keys(menuItems).length - 1]].id);
+    if (subitems.size > 0) {
+      setListboxHighlight(subitems.get(Array.from(subitems.keys())[subitems.size - 1])!.id);
     }
-  }, [menuItems, setListboxHighlight]);
+  }, [subitems, setListboxHighlight]);
 
   React.useEffect(() => {
-    if (!open) {
+    if (open) {
+      // TODO: ignore disabled items
       highlightFirstItem();
+      subitems.get(subitemKeys[0])?.ref?.current?.focus();
     }
-  }, [open, highlightFirstItem]);
+  }, [open, highlightFirstItem, subitems, subitemKeys]);
 
   const createHandleKeyDown = (otherHandlers: EventHandlers) => (e: React.KeyboardEvent) => {
     otherHandlers.onKeyDown?.(e);
@@ -137,9 +133,9 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
   React.useEffect(() => {
     // set focus to the highlighted item (but prevent stealing focus from other elements on the page)
     if (listboxRef.current?.contains(document.activeElement) && highlightedOption !== null) {
-      menuItems?.[highlightedOption]?.ref.current?.focus();
+      subitems?.get(highlightedOption)?.ref.current?.focus();
     }
-  }, [highlightedOption, menuItems]);
+  }, [highlightedOption, subitems]);
 
   const getListboxProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
@@ -156,41 +152,17 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     };
   };
 
-  const getItemState = React.useCallback(
-    (id: string): MenuItemState => {
-      const { disabled, highlighted } = getOptionState(id);
-      return { disabled, highlighted };
-    },
-    [getOptionState],
-  );
-
-  React.useDebugValue({ menuItems, highlightedOption });
-
-  const contextValue: MenuUnstyledContextType = React.useMemo(
-    () => ({
-      getItemProps: getOptionProps,
-      getItemState,
-      registerHighlightChangeHandler,
-      registerItem,
-      unregisterItem,
-      open,
-    }),
-    [
-      getOptionProps,
-      getItemState,
-      registerHighlightChangeHandler,
-      registerItem,
-      unregisterItem,
-      open,
-    ],
-  );
+  React.useDebugValue({ subitems, highlightedOption });
 
   return {
-    contextValue,
+    contextValue: {
+      ...compoundComponentContextValue,
+      ...listContextValue,
+    },
     getListboxProps,
     highlightedOption,
     highlightFirstItem,
     highlightLastItem,
-    menuItems,
+    menuItems: subitems,
   };
 }
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 3b5b0a007e1f0b..0d0909831ecf7e 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { MenuItemMetadata } from '../MenuItemUnstyled/MenuItemUnstyled.types';
-import { MenuUnstyledContextType } from '../MenuUnstyled/MenuUnstyledContext';
-import { UseListboxRootSlotProps } from '../useListbox';
+import { UseListRootSlotProps } from '../useList';
+import { MenuItemMetadata } from '../useMenuItem';
 import { EventHandlers } from '../utils/types';
+import { MenuProviderValue } from './MenuProvider';
 
 export interface UseMenuParameters {
   open?: boolean;
@@ -15,7 +15,7 @@ export interface UseMenuReturnValue {
   /**
    * The value for the menu context.
    */
-  contextValue: MenuUnstyledContextType;
+  contextValue: MenuProviderValue;
   /**
    * Resolver for the listbox component's props.
    * @param otherHandlers event handlers for the listbox component
@@ -39,7 +39,7 @@ export interface UseMenuReturnValue {
   /**
    * Items in the menu listbox.
    */
-  menuItems: Record<string, MenuItemMetadata>;
+  menuItems: Map<string, MenuItemMetadata>;
 }
 
 interface UseMenuListboxSlotEventHandlers {
@@ -47,7 +47,7 @@ interface UseMenuListboxSlotEventHandlers {
   onKeyDown: React.KeyboardEventHandler;
 }
 
-export type UseMenuListboxSlotProps<TOther = {}> = UseListboxRootSlotProps<
+export type UseMenuListboxSlotProps<TOther = {}> = UseListRootSlotProps<
   Omit<TOther, keyof UseMenuListboxSlotEventHandlers> & UseMenuListboxSlotEventHandlers
 > & {
   ref: React.Ref<any>;
diff --git a/packages/mui-base/src/useMenuItem/useMenuItem.ts b/packages/mui-base/src/useMenuItem/useMenuItem.ts
index 0c587f70ebf85b..0c1ba8e7047335 100644
--- a/packages/mui-base/src/useMenuItem/useMenuItem.ts
+++ b/packages/mui-base/src/useMenuItem/useMenuItem.ts
@@ -1,14 +1,15 @@
 import * as React from 'react';
 import { unstable_useId as useId, unstable_useForkRef as useForkRef } from '@mui/utils';
 import { EventHandlers } from '../utils/types';
-import { MenuUnstyledContext } from '../MenuUnstyled';
 import useButton from '../useButton';
 import {
+  MenuItemMetadata,
   UseMenuItemParameters,
   UseMenuItemReturnValue,
   UseMenuItemRootSlotProps,
 } from './useMenuItem.types';
-import useForcedRerendering from '../utils/useForcedRerendering';
+import { useListItem } from '../useList';
+import { useCompoundItem } from '../utils/useCompound';
 
 /**
  *
@@ -20,76 +21,42 @@ import useForcedRerendering from '../utils/useForcedRerendering';
  *
  * - [useMenuItem API](https://mui.com/base/react-menu/hooks-api/#use-menu-item)
  */
-export default function useMenuItem(props: UseMenuItemParameters): UseMenuItemReturnValue {
-  const { disabled = false, ref, label } = props;
-
-  const id = useId();
-  const menuContext = React.useContext(MenuUnstyledContext);
+export default function useMenuItem(params: UseMenuItemParameters): UseMenuItemReturnValue {
+  const { disabled = false, id: idParam, ref: externalRef, label } = params;
 
+  const id = useId(idParam);
   const itemRef = React.useRef<HTMLElement>(null);
-  const handleRef = useForkRef(itemRef, ref);
-
-  if (menuContext === null) {
-    throw new Error('MenuItemUnstyled must be used within a MenuUnstyled');
-  }
-
-  const { registerItem, unregisterItem, open, registerHighlightChangeHandler } = menuContext;
 
-  React.useEffect(() => {
-    if (id === undefined) {
-      return undefined;
-    }
+  const itemMetadata: MenuItemMetadata = React.useMemo(
+    () => ({ disabled, id: id ?? '', label, ref: itemRef }),
+    [disabled, id, label],
+  );
 
-    registerItem(id, { disabled, id, ref: itemRef, label });
+  const {
+    getRootProps: getListRootProps,
+    highlighted,
+    ref: listItemRefHandler,
+  } = useListItem({
+    item: id,
+  });
 
-    return () => unregisterItem(id);
-  }, [id, registerItem, unregisterItem, disabled, ref, label]);
+  const { index, totalItemCount } = useCompoundItem(id, itemMetadata);
 
-  const { getRootProps: getButtonProps, focusVisible } = useButton({
+  const {
+    getRootProps: getButtonProps,
+    focusVisible,
+    ref: buttonRefHandler,
+  } = useButton({
     disabled,
     focusableWhenDisabled: true,
-    ref: handleRef,
   });
 
-  // Ensure the menu item is focused when highlighted
-  const [focusRequested, requestFocus] = React.useState(false);
-
-  const focusIfRequested = React.useCallback(() => {
-    if (focusRequested && itemRef.current != null) {
-      itemRef.current.focus();
-      requestFocus(false);
-    }
-  }, [focusRequested]);
-
-  React.useEffect(() => {
-    focusIfRequested();
-  });
-
-  React.useDebugValue({ id, disabled, label });
-
-  const itemState = menuContext.getItemState(id ?? '');
-
-  const { highlighted } = itemState ?? { highlighted: false };
-
-  const rerender = useForcedRerendering();
-
-  React.useEffect(() => {
-    function updateHighlightedState(highlightedItemId: string | null) {
-      if (highlightedItemId === id && !highlighted) {
-        rerender();
-      } else if (highlightedItemId !== id && highlighted) {
-        rerender();
-      }
-    }
+  const handleRef = useForkRef(listItemRefHandler, buttonRefHandler, externalRef, itemRef);
 
-    return registerHighlightChangeHandler(updateHighlightedState);
-  });
-
-  React.useEffect(() => {
-    // TODO: this should be handled by the MenuButton
-    requestFocus(highlighted && open);
-  }, [highlighted, open]);
+  React.useDebugValue({ id, highlighted, disabled, label });
 
+  // If `id` is undefined (during SSR in React < 18), we fall back to rendering a simplified menu item
+  // which does not have access to infortmation about its position or highlighted state.
   if (id === undefined) {
     return {
       getRootProps: <TOther extends EventHandlers = {}>(
@@ -102,25 +69,40 @@ export default function useMenuItem(props: UseMenuItemParameters): UseMenuItemRe
       disabled: false,
       focusVisible,
       highlighted: false,
+      index: -1,
+      totalItemCount: 0,
+      ref: handleRef,
     };
   }
 
-  return {
-    getRootProps: <TOther extends EventHandlers = {}>(
-      otherHandlers: TOther = {} as TOther,
-    ): UseMenuItemRootSlotProps<TOther> => {
-      const optionProps = menuContext.getItemProps(id, otherHandlers);
+  const getRootProps = <TOther extends EventHandlers = {}>(
+    otherHandlers: TOther = {} as TOther,
+  ): UseMenuItemRootSlotProps<TOther> => {
+    const resolvedMenuItemProps = {
+      ...otherHandlers,
+      ...getListRootProps(otherHandlers),
+    };
 
-      return {
-        ...otherHandlers,
-        ...getButtonProps(otherHandlers),
-        tabIndex: optionProps.tabIndex,
-        id: optionProps.id,
-        role: 'menuitem',
-      };
-    },
-    disabled: itemState?.disabled ?? false,
+    const resolvedButtonProps = {
+      ...resolvedMenuItemProps,
+      ...getButtonProps(resolvedMenuItemProps),
+    };
+
+    return {
+      ...otherHandlers,
+      ...resolvedButtonProps,
+      role: 'menuitem',
+      ref: handleRef,
+    };
+  };
+
+  return {
+    getRootProps,
+    disabled,
     focusVisible,
     highlighted,
+    index,
+    totalItemCount,
+    ref: handleRef,
   };
 }
diff --git a/packages/mui-base/src/useMenuItem/useMenuItem.types.ts b/packages/mui-base/src/useMenuItem/useMenuItem.types.ts
index ba2c1edabdecea..6a4bd202a2fd94 100644
--- a/packages/mui-base/src/useMenuItem/useMenuItem.types.ts
+++ b/packages/mui-base/src/useMenuItem/useMenuItem.types.ts
@@ -7,12 +7,20 @@ interface UseMenuItemRootSlotOwnProps {
   id?: string;
 }
 
+export interface MenuItemMetadata {
+  id: string;
+  disabled: boolean;
+  label?: string;
+  ref: React.RefObject<HTMLElement>;
+}
+
 export type UseMenuItemRootSlotProps<TOther = {}> = TOther &
   UseMenuItemRootSlotOwnProps &
   UseButtonRootSlotProps<TOther>;
 
 export interface UseMenuItemParameters {
   disabled?: boolean;
+  id?: string;
   onClick?: React.MouseEventHandler<any>;
   ref: React.Ref<any>;
   label?: string;
@@ -29,17 +37,26 @@ export interface UseMenuItemReturnValue {
   ) => UseMenuItemRootSlotProps<TOther>;
   /**
    * If `true`, the component is disabled.
-   * @default false
    */
   disabled: boolean;
   /**
    * If `true`, the component is being focused using keyboard.
-   * @default false
    */
   focusVisible: boolean;
   /**
    * If `true`, the component is being highlighted.
-   * @default false
    */
   highlighted: boolean;
+  /**
+   * 0-based index of the item in the menu.
+   */
+  index: number;
+  /**
+   * The ref to the component's root DOM element.
+   */
+  ref: ((instance: unknown) => void) | null;
+  /**
+   * Total number of items in the menu.
+   */
+  totalItemCount: number;
 }
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index d4d109a64956f9..00efac9a22a4fd 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -71,6 +71,7 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
       ...resolvedButtonProps,
       role: 'tab',
       'aria-controls': 'not-implemented-yet',
+      'aria-selected': selected,
       id: tabId,
       ref: handleRef,
     };
diff --git a/packages/mui-base/src/utils/useCompound.ts b/packages/mui-base/src/utils/useCompound.ts
index 3d7350f16b78a7..76d1bc7dee7af3 100644
--- a/packages/mui-base/src/utils/useCompound.ts
+++ b/packages/mui-base/src/utils/useCompound.ts
@@ -90,13 +90,13 @@ export interface UseCompoundItemReturnValue {
 /**
  * Registers a child component with the parent component.
  *
- * @param id A unique key for the child component
+ * @param id A unique key for the child component. If the `id` is `undefined`, the registration logic will not run (this can sometimes be the case during SSR).
  * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
  *
  * @ignore - internal hook.
  */
 export function useCompoundItem<Key, Subitem>(
-  id: Key,
+  id: Key | undefined,
   itemMetadata: Subitem,
 ): UseCompoundItemReturnValue {
   const context = React.useContext(CompoundComponentContext) as CompoundComponentContextValue<
@@ -111,13 +111,17 @@ export function useCompoundItem<Key, Subitem>(
   const { registerItem, unregisterItem } = context;
 
   React.useEffect(() => {
+    if (id === undefined) {
+      return () => {};
+    }
+
     registerItem(id, itemMetadata);
 
     return () => unregisterItem(id);
   }, [id, registerItem, unregisterItem, itemMetadata]);
 
   return {
-    index: context.getItemIndex(id),
+    index: id !== undefined ? context.getItemIndex(id) : -1,
     totalItemCount: context.totalSubitemCount,
   };
 }

From db53bd01b03ec5465d20b38e9ea95df2e4d9dfa8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 21 Mar 2023 14:11:19 +0100
Subject: [PATCH 07/49] Use the new building blocks in SelectUnstyled

---
 docs/data/base/components/select/UseSelect.js |  11 +-
 .../data/base/components/select/UseSelect.tsx |  29 +--
 docs/pages/experiments/base/listbox.tsx       |  14 +-
 .../OptionUnstyled/OptionUnstyled.test.tsx    |  41 ++--
 .../src/OptionUnstyled/OptionUnstyled.tsx     |  10 +-
 .../OptionUnstyled/OptionUnstyled.types.ts    |  11 +-
 .../SelectUnstyled/SelectUnstyled.test.tsx    |  13 +-
 .../src/SelectUnstyled/SelectUnstyled.tsx     |  61 +++---
 .../SelectUnstyled/SelectUnstyled.types.ts    |  10 +-
 .../SelectUnstyled/SelectUnstyledContext.ts   |  20 --
 .../defaultOptionStringifier.ts               |   2 +-
 packages/mui-base/src/SelectUnstyled/index.ts |   4 -
 .../mui-base/src/SelectUnstyled/utils.tsx     |  75 -------
 .../mui-base/src/useList/useList.test.tsx     |  85 ++------
 packages/mui-base/src/useList/useList.ts      |  26 ++-
 .../mui-base/src/useList/useList.types.ts     |   7 +-
 packages/mui-base/src/useList/useListItem.ts  |   1 -
 .../mui-base/src/useMenuItem/useMenuItem.ts   |  11 +-
 packages/mui-base/src/useOption/useOption.ts  | 106 +++-------
 .../mui-base/src/useOption/useOption.types.ts |  19 +-
 .../mui-base/src/useSelect/SelectProvider.tsx |  63 ++++++
 packages/mui-base/src/useSelect/index.ts      |   3 +
 packages/mui-base/src/useSelect/useSelect.ts  | 195 ++++++++++--------
 .../mui-base/src/useSelect/useSelect.types.ts |  64 ++----
 .../useSelectChangeNotifiers.test.tsx         | 121 -----------
 .../src/useSelect/useSelectChangeNotifiers.ts |  70 -------
 packages/mui-joy/src/Select/SelectProps.ts    |   4 +-
 27 files changed, 371 insertions(+), 705 deletions(-)
 delete mode 100644 packages/mui-base/src/SelectUnstyled/SelectUnstyledContext.ts
 delete mode 100644 packages/mui-base/src/SelectUnstyled/utils.tsx
 create mode 100644 packages/mui-base/src/useSelect/SelectProvider.tsx
 delete mode 100644 packages/mui-base/src/useSelect/useSelectChangeNotifiers.test.tsx
 delete mode 100644 packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts

diff --git a/docs/data/base/components/select/UseSelect.js b/docs/data/base/components/select/UseSelect.js
index da15812ce309a3..22ecdf2d1f02a1 100644
--- a/docs/data/base/components/select/UseSelect.js
+++ b/docs/data/base/components/select/UseSelect.js
@@ -1,9 +1,10 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { useSelect, useOption, SelectUnstyledContext } from '@mui/base';
 import { styled } from '@mui/system';
 import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 import clsx from 'clsx';
+import useSelect, { SelectProvider } from '@mui/base/useSelect';
+import useOption from '@mui/base/useOption';
 
 const blue = {
   100: '#DAECFF',
@@ -150,6 +151,7 @@ function CustomOption(props) {
   const { getRootProps, highlighted } = useOption({
     value,
     disabled,
+    label: children,
   });
 
   return (
@@ -178,7 +180,6 @@ function CustomSelect({ options, placeholder }) {
     listboxRef,
     onOpenChange: setListboxVisible,
     open: listboxVisible,
-    options,
   });
 
   React.useEffect(() => {
@@ -201,7 +202,7 @@ function CustomSelect({ options, placeholder }) {
         aria-hidden={!listboxVisible}
         className={listboxVisible ? '' : 'hidden'}
       >
-        <SelectUnstyledContext.Provider value={contextValue}>
+        <SelectProvider value={contextValue}>
           {options.map((option) => {
             return (
               <CustomOption key={option.value} value={option.value}>
@@ -209,7 +210,7 @@ function CustomSelect({ options, placeholder }) {
               </CustomOption>
             );
           })}
-        </SelectUnstyledContext.Provider>
+        </SelectProvider>
       </Listbox>
     </Root>
   );
@@ -219,7 +220,7 @@ CustomSelect.propTypes = {
   options: PropTypes.arrayOf(
     PropTypes.shape({
       disabled: PropTypes.bool,
-      label: PropTypes.node,
+      label: PropTypes.string.isRequired,
       value: PropTypes.string.isRequired,
     }),
   ).isRequired,
diff --git a/docs/data/base/components/select/UseSelect.tsx b/docs/data/base/components/select/UseSelect.tsx
index 93e036a2702a5c..78b115c97e309d 100644
--- a/docs/data/base/components/select/UseSelect.tsx
+++ b/docs/data/base/components/select/UseSelect.tsx
@@ -1,13 +1,12 @@
 import * as React from 'react';
-import {
-  useSelect,
-  SelectOption,
-  useOption,
-  SelectUnstyledContext,
-} from '@mui/base';
 import { styled } from '@mui/system';
 import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 import clsx from 'clsx';
+import useSelect, {
+  SelectOptionDefinition,
+  SelectProvider,
+} from '@mui/base/useSelect';
+import useOption from '@mui/base/useOption';
 
 const blue = {
   100: '#DAECFF',
@@ -144,7 +143,7 @@ const Option = styled('li')(
 );
 
 interface Props {
-  options: SelectOption<string>[];
+  options: SelectOptionDefinition<string>[];
   placeholder?: string;
 }
 
@@ -155,7 +154,10 @@ interface OptionProps {
   disabled?: boolean;
 }
 
-function renderSelectedValue(value: string | null, options: SelectOption<string>[]) {
+function renderSelectedValue(
+  value: string | null,
+  options: SelectOptionDefinition<string>[],
+) {
   const selectedOption = options.find((option) => option.value === value);
 
   return selectedOption ? `${selectedOption.label} (${value})` : null;
@@ -166,6 +168,7 @@ function CustomOption(props: OptionProps) {
   const { getRootProps, highlighted } = useOption({
     value,
     disabled,
+    label: children,
   });
 
   return (
@@ -183,11 +186,13 @@ function CustomSelect({ options, placeholder }: Props) {
   const listboxRef = React.useRef<HTMLUListElement>(null);
   const [listboxVisible, setListboxVisible] = React.useState(false);
 
-  const { getButtonProps, getListboxProps, contextValue, value } = useSelect({
+  const { getButtonProps, getListboxProps, contextValue, value } = useSelect<
+    string,
+    false
+  >({
     listboxRef,
     onOpenChange: setListboxVisible,
     open: listboxVisible,
-    options,
   });
 
   React.useEffect(() => {
@@ -210,7 +215,7 @@ function CustomSelect({ options, placeholder }: Props) {
         aria-hidden={!listboxVisible}
         className={listboxVisible ? '' : 'hidden'}
       >
-        <SelectUnstyledContext.Provider value={contextValue}>
+        <SelectProvider value={contextValue}>
           {options.map((option) => {
             return (
               <CustomOption key={option.value} value={option.value}>
@@ -218,7 +223,7 @@ function CustomSelect({ options, placeholder }: Props) {
               </CustomOption>
             );
           })}
-        </SelectUnstyledContext.Provider>
+        </SelectProvider>
       </Listbox>
     </Root>
   );
diff --git a/docs/pages/experiments/base/listbox.tsx b/docs/pages/experiments/base/listbox.tsx
index 36f8526f9dcc1a..349c4bb1a0b8c5 100644
--- a/docs/pages/experiments/base/listbox.tsx
+++ b/docs/pages/experiments/base/listbox.tsx
@@ -89,10 +89,10 @@ const styles = `
 const items = Array.from({ length: 200 }, (_, i) => i + 1);
 
 const Item = React.forwardRef(function Item(
-  props: React.PropsWithChildren<{ value: number }>,
+  props: React.PropsWithChildren<{ value: number; id?: string }>,
   ref: React.Ref<HTMLElement>,
 ) {
-  const item = props.value;
+  const { value: item, id } = props;
   const { getRootProps, selected, highlighted } = useListItem({ item, ref });
 
   const itemProps = getRootProps();
@@ -103,7 +103,7 @@ const Item = React.forwardRef(function Item(
   });
 
   return (
-    <div {...itemProps} className={classes}>
+    <div {...itemProps} className={classes} id={id}>
       {item}
     </div>
   );
@@ -134,6 +134,7 @@ function List() {
   const listbox = useList({
     items,
     getItemDomElement: (item) => itemRefs.current.get(item) || null,
+    getItemId: (item) => `item-${item}`,
     orientation,
     focusManagement,
     selectionLimit: 1,
@@ -201,7 +202,12 @@ function List() {
       <div {...getRootProps()} className="list" style={{ flexDirection }}>
         <ListContext.Provider value={contextValue}>
           {items.map((item) => (
-            <Item key={item} value={item} ref={(node) => handleItemRef(item, node)} />
+            <Item
+              key={item}
+              value={item}
+              ref={(node) => handleItemRef(item, node)}
+              id={`item-${item}`}
+            />
           ))}
         </ListContext.Provider>
       </div>
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
index 4ef38533a7d0e3..50520ec8d3df43 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
@@ -1,23 +1,14 @@
 import * as React from 'react';
 import { createMount, createRenderer, describeConformanceUnstyled } from 'test/utils';
 import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
-import { SelectUnstyledContext } from '@mui/base/SelectUnstyled';
+import SelectProvider from '../useSelect/SelectProvider';
 
-const dummyGetOptionState = () => ({
+const dummyGetItemState = () => ({
   disabled: false,
   highlighted: false,
   selected: false,
   index: 0,
-});
-
-const dummyGetOptionProps = () => ({
-  'aria-disabled': false,
-  'aria-selected': false,
-  label: '',
-  onClick: () => {},
-  onPointerOver: () => {},
-  role: 'option',
-  value: '',
+  focusable: undefined,
 });
 
 describe('<OptionUnstyled />', () => {
@@ -28,32 +19,38 @@ describe('<OptionUnstyled />', () => {
     inheritComponent: 'li',
     render: (node) => {
       return render(
-        <SelectUnstyledContext.Provider
+        <SelectProvider
           value={{
-            getOptionState: dummyGetOptionState,
-            getOptionProps: dummyGetOptionProps,
-            listboxRef: React.createRef(),
+            dispatch: () => {},
+            getItemIndex: () => 0,
+            getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
+            registerItem: () => () => {},
             registerSelectionChangeHandler: () => () => {},
+            totalSubitemCount: 0,
+            unregisterItem: () => () => {},
           }}
         >
           {node}
-        </SelectUnstyledContext.Provider>,
+        </SelectProvider>,
       );
     },
     mount: (node: React.ReactNode) => {
       const wrapper = mount(
-        <SelectUnstyledContext.Provider
+        <SelectProvider
           value={{
-            getOptionState: dummyGetOptionState,
-            getOptionProps: dummyGetOptionProps,
-            listboxRef: React.createRef(),
+            dispatch: () => {},
+            getItemIndex: () => 0,
+            getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
+            registerItem: () => () => {},
             registerSelectionChangeHandler: () => () => {},
+            totalSubitemCount: 0,
+            unregisterItem: () => () => {},
           }}
         >
           {node}
-        </SelectUnstyledContext.Provider>,
+        </SelectProvider>,
       );
       return wrapper.childAt(0);
     },
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
index 44684aef14029e..8f088b00527b8d 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
@@ -1,19 +1,17 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { OptionState } from '../useListbox';
 import composeClasses from '../composeClasses';
 import {
   OptionUnstyledProps,
   OptionUnstyledOwnerState,
   OptionUnstyledType,
 } from './OptionUnstyled.types';
-import { SelectUnstyledContext } from '../SelectUnstyled/SelectUnstyledContext';
 import { getOptionUnstyledUtilityClass } from './optionUnstyledClasses';
 import { useSlotProps } from '../utils';
 import useOption from '../useOption';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
 
-function useUtilityClasses(ownerState: OptionState) {
+function useUtilityClasses<TValue>(ownerState: OptionUnstyledOwnerState<TValue>) {
   const { disabled, highlighted, selected } = ownerState;
 
   const slots = {
@@ -41,17 +39,13 @@ const OptionUnstyled = React.forwardRef(function OptionUnstyled<TValue>(
     ...other
   } = props;
 
-  const selectContext = React.useContext(SelectUnstyledContext);
-  if (!selectContext) {
-    throw new Error('OptionUnstyled must be used within a SelectUnstyled');
-  }
-
   const Root = component || slots.root || 'li';
 
   const { getRootProps, selected, highlighted, index } = useOption({
     disabled,
     value,
     optionRef: ref,
+    label: label || children,
   });
 
   const ownerState: OptionUnstyledOwnerState<TValue> = {
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
index eaa1fa083cbf30..e90c6ee042805f 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
@@ -1,7 +1,6 @@
 import * as React from 'react';
 import { DefaultComponentProps, OverrideProps, Simplify } from '@mui/types';
-import { OptionState } from '../useListbox';
-import { UseSelectOptionSlotProps } from '../useSelect';
+import { UseOptionRootSlotProps } from '../useOption';
 import { SlotComponentProps } from '../utils';
 
 export interface OptionUnstyledRootSlotPropsOverrides {}
@@ -77,11 +76,15 @@ export interface OptionUnstyledType {
 }
 
 export type OptionUnstyledOwnerState<TValue> = Simplify<
-  OptionUnstyledOwnProps<TValue> & OptionState
+  OptionUnstyledOwnProps<TValue> & {
+    selected: boolean;
+    highlighted: boolean;
+    index: number;
+  }
 >;
 
 export type OptionUnstyledRootSlotProps<TValue> = Simplify<
-  UseSelectOptionSlotProps & {
+  UseOptionRootSlotProps & {
     children?: React.ReactNode;
     className: string;
     ref: React.Ref<HTMLLIElement>;
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index f97a9fb4a929e9..5ada0e043f8584 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
 import SelectUnstyled, { selectUnstyledClasses } from '@mui/base/SelectUnstyled';
-import { SelectOption } from '@mui/base/useSelect';
+import { SelectOption } from '@mui/base/useOption';
 import OptionUnstyled, {
   OptionUnstyledProps,
   optionUnstyledClasses,
@@ -23,7 +23,7 @@ describe('<SelectUnstyled />', () => {
   const { render } = createRenderer();
 
   const componentToTest = (
-    <SelectUnstyled defaultListboxOpen>
+    <SelectUnstyled defaultListboxOpen slotProps={{ popper: { disablePortal: true } }}>
       <OptionGroupUnstyled label="Group">
         <OptionUnstyled value={1}>1</OptionUnstyled>
       </OptionGroupUnstyled>
@@ -85,7 +85,7 @@ describe('<SelectUnstyled />', () => {
 
     ['Enter', ' ', 'Escape'].forEach((key) => {
       it(`closes the dropdown when the "${key}" key is pressed`, () => {
-        const { getByRole, queryByRole } = render(
+        const { getByRole } = render(
           <SelectUnstyled>
             <OptionUnstyled value={1}>1</OptionUnstyled>
           </SelectUnstyled>,
@@ -99,7 +99,7 @@ describe('<SelectUnstyled />', () => {
         userEvent.keyPress(listbox, { key });
 
         expect(select).to.have.attribute('aria-expanded', 'false');
-        expect(queryByRole('listbox')).to.equal(null);
+        expect(listbox).not.toBeVisible();
       });
     });
 
@@ -142,7 +142,7 @@ describe('<SelectUnstyled />', () => {
 
           userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '1'
           userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '2'
-          userEvent.keyPress(listbox, { key });
+          fireEvent.keyDown(listbox, { key });
 
           expect(select).to.have.text('2');
         }),
@@ -356,7 +356,7 @@ describe('<SelectUnstyled />', () => {
 
       expect(select).to.have.attribute('aria-expanded', 'false');
       expect(select).to.have.text('1');
-      expect(queryByRole('listbox')).to.equal(null);
+      expect(queryByRole('listbox')).not.toBeVisible();
     });
   });
 
@@ -846,6 +846,7 @@ describe('<SelectUnstyled />', () => {
 
     expect(select).to.have.attribute('aria-expanded', 'false');
     expect(select).to.have.text('1');
+    expect(listbox).not.toBeVisible();
   });
 
   it('closes the listbox when already selected option is selected again with a click', () => {
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
index 8a22de42645dc5..6913f36a966686 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
@@ -12,15 +12,15 @@ import {
   SelectUnstyledRootSlotProps,
   SelectUnstyledType,
 } from './SelectUnstyled.types';
-import { flattenOptionGroups, getOptionsFromChildren } from './utils';
-import useSelect, { SelectChild, SelectOption, SelectValue } from '../useSelect';
+import useSelect, { SelectValue } from '../useSelect';
 import { useSlotProps, WithOptionalOwnerState } from '../utils';
 import PopperUnstyled from '../PopperUnstyled';
-import { SelectUnstyledContext } from './SelectUnstyledContext';
 import composeClasses from '../composeClasses';
 import { getSelectUnstyledUtilityClass } from './selectUnstyledClasses';
 import defaultOptionStringifier from './defaultOptionStringifier';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
+import { SelectOption } from '../useOption';
+import SelectProvider from '../useSelect/SelectProvider';
 
 function defaultRenderValue<TValue>(
   selectedOptions: SelectOption<TValue> | SelectOption<TValue>[] | null,
@@ -120,10 +120,9 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     ...other
   } = props;
 
-  const renderValue = renderValueProp ?? defaultRenderValue;
+  const renderValue: (option: SelectValue<SelectOption<TValue>, Multiple>) => React.ReactNode =
+    renderValueProp ?? defaultRenderValue;
 
-  const [groupedOptions, setGroupedOptions] = React.useState<SelectChild<TValue>[]>([]);
-  const options = React.useMemo(() => flattenOptionGroups(groupedOptions), [groupedOptions]);
   const [listboxOpen, setListboxOpen] = useControlled({
     controlled: listboxOpenProp,
     default: defaultListboxOpen,
@@ -131,10 +130,6 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     state: 'listboxOpen',
   });
 
-  React.useEffect(() => {
-    setGroupedOptions(getOptionsFromChildren(children));
-  }, [children]);
-
   const [buttonDefined, setButtonDefined] = React.useState(false);
   const buttonRef = React.useRef<HTMLElement | null>(null);
   const listboxRef = React.useRef<HTMLElement>(null);
@@ -166,10 +161,11 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
   const {
     buttonActive,
     buttonFocusVisible,
+    contextValue,
     disabled,
     getButtonProps,
     getListboxProps,
-    contextValue,
+    getOptionMetadata,
     value,
   } = useSelect({
     buttonRef: handleButtonRef,
@@ -180,7 +176,6 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     open: listboxOpen,
     onChange,
     onOpenChange: handleOpenChange,
-    options,
     optionStringifier,
     value: valueProp,
   });
@@ -199,24 +194,6 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
 
   const classes = useUtilityClasses(ownerState);
 
-  const selectedOption: SelectValue<SelectOption<TValue>, Multiple> = React.useMemo(() => {
-    if (multiple) {
-      if (value == null) {
-        return [] as unknown as SelectValue<SelectOption<TValue>, Multiple>;
-      }
-
-      return options.filter((o) => (value as TValue[]).includes(o.value)) as SelectValue<
-        SelectOption<TValue>,
-        Multiple
-      >;
-    }
-
-    return (options.find((o) => value === o.value) ?? null) as SelectValue<
-      SelectOption<TValue>,
-      Multiple
-    >;
-  }, [options, value, multiple]);
-
   const buttonProps: WithOptionalOwnerState<SelectUnstyledRootSlotProps<TValue, Multiple>> =
     useSlotProps({
       elementType: Button,
@@ -244,7 +221,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     externalSlotProps: slotProps.popper,
     additionalProps: {
       anchorEl: buttonRef.current,
-      disablePortal: true,
+      keepMounted: true,
       open: listboxOpen,
       placement: 'bottom-start' as const,
       role: undefined,
@@ -253,20 +230,32 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     className: classes.popper,
   });
 
+  let selectedOptionsMetadata: SelectValue<SelectOption<TValue>, Multiple>;
+  if (multiple) {
+    selectedOptionsMetadata = (value as TValue[])
+      .map((v) => getOptionMetadata(v))
+      .filter((o) => o !== undefined) as SelectValue<SelectOption<TValue>, Multiple>;
+  } else {
+    selectedOptionsMetadata = (getOptionMetadata(value as TValue) ?? null) as SelectValue<
+      SelectOption<TValue>,
+      Multiple
+    >;
+  }
+
   return (
     <React.Fragment>
-      <Button {...buttonProps}>{renderValue(selectedOption as any)}</Button>
+      <Button {...buttonProps}>{renderValue(selectedOptionsMetadata)}</Button>
       {buttonDefined && (
         <Popper {...popperProps}>
           <ListboxRoot {...listboxProps}>
-            <SelectUnstyledContext.Provider value={contextValue}>
-              {children}
-            </SelectUnstyledContext.Provider>
+            <SelectProvider value={contextValue}>{children}</SelectProvider>
           </ListboxRoot>
         </Popper>
       )}
 
-      {name && <input type="hidden" name={name} value={getSerializedValue(selectedOption)} />}
+      {name && (
+        <input type="hidden" name={name} value={getSerializedValue(selectedOptionsMetadata)} />
+      )}
     </React.Fragment>
   );
 }) as SelectUnstyledType;
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
index c9d0bc4832c458..559256080d0fc6 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
@@ -1,11 +1,7 @@
 import * as React from 'react';
 import { DefaultComponentProps, OverrideProps, Simplify } from '@mui/types';
-import {
-  SelectOption,
-  SelectValue,
-  UseSelectButtonSlotProps,
-  UseSelectListboxSlotProps,
-} from '../useSelect';
+import { SelectValue, UseSelectButtonSlotProps, UseSelectListboxSlotProps } from '../useSelect';
+import { SelectOption } from '../useOption';
 import PopperUnstyled, { PopperUnstyledProps } from '../PopperUnstyled';
 import { SlotComponentProps } from '../utils';
 
@@ -203,7 +199,7 @@ export type SelectUnstyledPopperSlotProps<TValue extends {}, Multiple extends bo
   anchorEl: PopperUnstyledProps['anchorEl'];
   children?: PopperUnstyledProps['children'];
   className?: string;
-  disablePortal: PopperUnstyledProps['disablePortal'];
+  keepMounted: PopperUnstyledProps['keepMounted'];
   open: boolean;
   ownerState: SelectUnstyledOwnerState<TValue, Multiple>;
   placement: PopperUnstyledProps['placement'];
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyledContext.ts b/packages/mui-base/src/SelectUnstyled/SelectUnstyledContext.ts
deleted file mode 100644
index ec64a0d351564a..00000000000000
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyledContext.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import * as React from 'react';
-import { OptionState } from '../useListbox';
-import { EventHandlers } from '../utils';
-import { UseSelectOptionSlotProps } from '../useSelect';
-import { SelectChangeNotifiers } from '../useSelect/useSelectChangeNotifiers';
-
-export interface SelectUnstyledContextType {
-  getOptionState: (value: any) => OptionState;
-  getOptionProps: <OtherHandlers extends EventHandlers>(
-    value: any,
-    otherHandlers: OtherHandlers,
-  ) => UseSelectOptionSlotProps;
-  listboxRef: React.RefObject<any>;
-  registerSelectionChangeHandler: SelectChangeNotifiers<any>['registerSelectionChangeHandler'];
-  registerHighlightChangeHandler: SelectChangeNotifiers<any>['registerHighlightChangeHandler'];
-}
-
-export const SelectUnstyledContext = React.createContext<SelectUnstyledContextType | undefined>(
-  undefined,
-);
diff --git a/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts b/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts
index 7573f1eb717826..6d193aa0533d3f 100644
--- a/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts
+++ b/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts
@@ -1,4 +1,4 @@
-import { SelectOption } from '../useSelect/useSelect.types';
+import { SelectOption } from '../useOption';
 
 const defaultOptionStringifier = <TValue>(option: SelectOption<TValue>) => {
   const { label, value } = option;
diff --git a/packages/mui-base/src/SelectUnstyled/index.ts b/packages/mui-base/src/SelectUnstyled/index.ts
index 4245c00702824b..74eed226187b47 100644
--- a/packages/mui-base/src/SelectUnstyled/index.ts
+++ b/packages/mui-base/src/SelectUnstyled/index.ts
@@ -1,10 +1,6 @@
 export { default } from './SelectUnstyled';
 
-export * from './SelectUnstyledContext';
-
 export { default as selectUnstyledClasses } from './selectUnstyledClasses';
 export * from './selectUnstyledClasses';
 
 export * from './SelectUnstyled.types';
-
-export * from './utils';
diff --git a/packages/mui-base/src/SelectUnstyled/utils.tsx b/packages/mui-base/src/SelectUnstyled/utils.tsx
deleted file mode 100644
index bbee32da77e7a0..00000000000000
--- a/packages/mui-base/src/SelectUnstyled/utils.tsx
+++ /dev/null
@@ -1,75 +0,0 @@
-import * as React from 'react';
-import { OptionUnstyledProps } from '../OptionUnstyled/OptionUnstyled.types';
-import { OptionGroupUnstyledProps } from '../OptionGroupUnstyled';
-import { isOptionGroup, SelectChild, SelectOption, SelectOptionGroup } from '../useSelect';
-
-export function areOptionsEqual<TValue>(
-  option1: SelectOption<TValue>,
-  option2: SelectOption<TValue>,
-) {
-  return (
-    option1.label === option2.label &&
-    option1.value === option2.value &&
-    option1.disabled === option2.disabled
-  );
-}
-
-export function getOptionsFromChildren<TValue>(children: React.ReactNode): SelectChild<TValue>[] {
-  if (children == null) {
-    return [];
-  }
-
-  const selectChildren: SelectChild<TValue>[] = [];
-
-  React.Children.forEach(children, (node: React.ReactNode) => {
-    const nodeChildren = (node as React.ReactElement)?.props?.children;
-    if ((node as React.ReactElement)?.props?.value === undefined) {
-      if (nodeChildren != null) {
-        const element = node as React.ReactElement<OptionGroupUnstyledProps>;
-
-        const group: SelectOptionGroup<TValue> = {
-          options: getOptionsFromChildren<TValue>(nodeChildren),
-          label: element.props.label,
-          disabled: element.props.disabled ?? false,
-        };
-
-        selectChildren.push(group);
-      }
-
-      return;
-    }
-
-    const element = node as React.ReactElement<OptionUnstyledProps<TValue>>;
-
-    const option = {
-      value: element.props.value,
-      label: element.props.label || element.props.children,
-      disabled: element.props.disabled ?? false,
-    };
-
-    selectChildren.push(option);
-  });
-
-  return selectChildren ?? [];
-}
-
-export function flattenOptionGroups<TValue>(
-  groupedOptions: SelectChild<TValue>[],
-  isGroupDisabled: boolean = false,
-): SelectOption<TValue>[] {
-  let flatOptions: SelectOption<TValue>[] = [];
-  groupedOptions.forEach((optionOrGroup) => {
-    if (isOptionGroup(optionOrGroup)) {
-      flatOptions = flatOptions.concat(
-        flattenOptionGroups(optionOrGroup.options, optionOrGroup.disabled),
-      );
-    } else {
-      flatOptions.push({
-        ...optionOrGroup,
-        disabled: isGroupDisabled || optionOrGroup.disabled,
-      });
-    }
-  });
-
-  return flatOptions;
-}
diff --git a/packages/mui-base/src/useList/useList.test.tsx b/packages/mui-base/src/useList/useList.test.tsx
index c6af0ec1e5d44f..efc4a6ff590b56 100644
--- a/packages/mui-base/src/useList/useList.test.tsx
+++ b/packages/mui-base/src/useList/useList.test.tsx
@@ -2,80 +2,19 @@ import * as React from 'react';
 import { expect } from 'chai';
 import { SinonSpy, spy } from 'sinon';
 import { createRenderer, createEvent, fireEvent } from 'test/utils';
-import useList, { ListContext } from './useList';
-import useListItem from './useListItem';
+import useList from './useList';
 
 describe('useList', () => {
   const { render } = createRenderer();
-  describe('prop: id', () => {
-    it('propagates it to the root element', () => {
-      function Listbox() {
-        const { getRootProps } = useList({ items: [], id: 'test-id' });
-        return <ul role="listbox" {...getRootProps()} />;
-      }
-      const { getByRole } = render(<Listbox />);
-
-      const listbox = getByRole('listbox');
-      expect(listbox).to.have.attribute('id', 'test-id');
-    });
-
-    it('uses the provided id to create option ids', () => {
-      const items = ['one', 'two'];
-
-      function ListItem({ children }: React.PropsWithChildren<{}>) {
-        const id = React.useId();
-        const { getRootProps, selected } = useListItem({ item: id });
-        return (
-          <li role="option" aria-selected={selected} {...getRootProps()}>
-            {children}
-          </li>
-        );
-      }
-
-      function Listbox() {
-        const { getRootProps, contextValue } = useList({ items, id: 'test-id' });
-        return (
-          <ListContext.Provider value={contextValue}>
-            <ul role="listbox" {...getRootProps()}>
-              {items.map((item) => (
-                <ListItem key={item}>{item}</ListItem>
-              ))}
-            </ul>
-          </ListContext.Provider>
-        );
-      }
-
-      const { getAllByRole } = render(<Listbox />);
-
-      const options = getAllByRole('option');
-      options.forEach((opt, index) =>
-        expect(opt).to.have.attribute('id', `test-id-option-${index}`),
-      );
-    });
-
-    it('generates a unique id if not provided explicitly', () => {
-      function Listbox() {
-        const { getRootProps } = useList({ items: [] });
-        return <ul role="listbox" {...getRootProps()} />;
-      }
-
-      const { getAllByRole } = render(
-        <React.Fragment>
-          <Listbox />
-          <Listbox />
-        </React.Fragment>,
-      );
-
-      const listboxes = getAllByRole('listbox');
-      expect(listboxes[0].id).not.to.equal(listboxes[1].id);
-    });
-  });
-
   describe('preventing default behavior on keyDown', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown', 'Enter', ' '].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in activeDescendant focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useList({ items: [], focusManagement: 'activeDescendant' });
+          const { getRootProps } = useList({
+            items: [],
+            focusManagement: 'activeDescendant',
+            getItemId: () => undefined,
+          });
           return <div role="listbox" {...getRootProps()} />;
         }
 
@@ -97,7 +36,11 @@ describe('useList', () => {
     ['ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'].forEach((key) =>
       it(`prevents default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
+          const { getRootProps } = useList({
+            items: [],
+            focusManagement: 'DOM',
+            getItemDomElement: () => null,
+          });
           return <div role="listbox" {...getRootProps()} />;
         }
 
@@ -119,7 +62,11 @@ describe('useList', () => {
     ['Enter', ' '].forEach((key) =>
       it(`does not prevent default behavior when ${key} is pressed in DOM focus management mode`, () => {
         function Listbox() {
-          const { getRootProps } = useList({ items: [], focusManagement: 'DOM' });
+          const { getRootProps } = useList({
+            items: [],
+            focusManagement: 'DOM',
+            getItemDomElement: () => null,
+          });
           return <div role="listbox" {...getRootProps()} />;
         }
 
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 0a59c4867021bb..4d00e62dbc8e0b 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { unstable_useForkRef as useForkRef, unstable_useId as useId } from '@mui/utils';
+import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import {
   UseListParameters,
   UseListParametersWithDefaults,
@@ -48,7 +48,7 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     disableListWrap = false,
     focusManagement = 'activeDescendant',
     getItemDomElement,
-    id: idProp,
+    getItemId,
     isItemDisabled = defaultIsItemDisabled,
     listRef: externalListRef,
     onHighlightChange,
@@ -61,14 +61,19 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     value: valueParam,
   } = params;
 
-  const id = useId(idProp);
-
-  const defaultIdGenerator = React.useCallback(
-    (_: ItemValue, index: number) => `${id}-option-${index}`,
-    [id],
-  );
+  if (process.env.NODE_ENV !== 'production') {
+    if (focusManagement === 'DOM' && getItemDomElement == null) {
+      throw new Error(
+        'The `getItemDomElement` prop is required when using the `DOM` focus management.',
+      );
+    }
 
-  const itemIdGenerator = params.itemIdGenerator ?? defaultIdGenerator;
+    if (focusManagement === 'activeDescendant' && getItemId == null) {
+      throw new Error(
+        'The `getItemId` prop is required when using the `activeDescendant` focus management.',
+      );
+    }
+  }
 
   const listRef = React.useRef<HTMLUListElement>(null);
   const handleRef = useForkRef(externalListRef, listRef);
@@ -261,9 +266,8 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
       ...otherHandlers,
       'aria-activedescendant':
         focusManagement === 'activeDescendant' && highlightedValue != null
-          ? itemIdGenerator(highlightedValue, highlightedIndex)
+          ? getItemId!(highlightedValue)
           : undefined,
-      id,
       onBlur: createHandleBlur(otherHandlers),
       onKeyDown: createHandleKeyDown(otherHandlers),
       tabIndex: focusManagement === 'DOM' ? -1 : 0,
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 6501d64da26125..9c438108aa8c3a 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -56,9 +56,12 @@ export interface UseListParameters<ItemValue> {
    */
   getItemDomElement?: (itemValue: ItemValue) => HTMLElement | null;
   /**
-   * Id attribute of the list component.
+   * A function that returns the id of an item.
+   * This is required to set `aria-activedescendant` and is required when using the `activeDescendant` focus management.
+   *
+   * @param itemValue List item to get the id for.
    */
-  id?: string;
+  getItemId?: (itemValue: ItemValue) => string | undefined;
   /**
    * A function that determines if a particular item is disabled.
    * @default () => false
diff --git a/packages/mui-base/src/useList/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
index cdd3432cad2d7c..420cb2552a29b3 100644
--- a/packages/mui-base/src/useList/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -109,7 +109,6 @@ export default function useListItem<ItemValue>(
     onPointerOver: createHandlePointerOver(otherHandlers),
     ref: handleRef,
     tabIndex,
-    // TODO: id
   });
 
   return {
diff --git a/packages/mui-base/src/useMenuItem/useMenuItem.ts b/packages/mui-base/src/useMenuItem/useMenuItem.ts
index 0c1ba8e7047335..18aa68e278ea8c 100644
--- a/packages/mui-base/src/useMenuItem/useMenuItem.ts
+++ b/packages/mui-base/src/useMenuItem/useMenuItem.ts
@@ -78,19 +78,20 @@ export default function useMenuItem(params: UseMenuItemParameters): UseMenuItemR
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
   ): UseMenuItemRootSlotProps<TOther> => {
-    const resolvedMenuItemProps = {
+    const resolvedButtonProps = {
       ...otherHandlers,
-      ...getListRootProps(otherHandlers),
+      ...getButtonProps(otherHandlers),
     };
 
-    const resolvedButtonProps = {
-      ...resolvedMenuItemProps,
-      ...getButtonProps(resolvedMenuItemProps),
+    const resolvedMenuItemProps = {
+      ...resolvedButtonProps,
+      ...getListRootProps(resolvedButtonProps),
     };
 
     return {
       ...otherHandlers,
       ...resolvedButtonProps,
+      ...resolvedMenuItemProps,
       role: 'menuitem',
       ref: handleRef,
     };
diff --git a/packages/mui-base/src/useOption/useOption.ts b/packages/mui-base/src/useOption/useOption.ts
index 9245291e34b619..b4b4933e288141 100644
--- a/packages/mui-base/src/useOption/useOption.ts
+++ b/packages/mui-base/src/useOption/useOption.ts
@@ -1,9 +1,9 @@
 import * as React from 'react';
-import { unstable_useForkRef as useForkRef } from '@mui/utils';
-import { SelectUnstyledContext } from '../SelectUnstyled/SelectUnstyledContext';
-import { UseOptionParameters, UseOptionReturnValue } from './useOption.types';
+import { unstable_useForkRef as useForkRef, unstable_useId as useId } from '@mui/utils';
+import { SelectOption, UseOptionParameters, UseOptionReturnValue } from './useOption.types';
 import { EventHandlers } from '../utils';
-import useForcedRerendering from '../utils/useForcedRerendering';
+import { useListItem } from '../useList';
+import { useCompoundItem } from '../utils/useCompound';
 
 /**
  *
@@ -16,91 +16,47 @@ import useForcedRerendering from '../utils/useForcedRerendering';
  * - [useOption API](https://mui.com/base/react-select/hooks-api/#use-option)
  */
 export default function useOption<Value>(params: UseOptionParameters<Value>): UseOptionReturnValue {
-  const { value, optionRef: optionRefParam } = params;
-
-  const selectContext = React.useContext(SelectUnstyledContext);
-  if (!selectContext) {
-    throw new Error(
-      'Option must have access to the SelectUnstyledContext (i.e., be used inside a SelectUnstyled component).',
-    );
-  }
+  const { value, label, disabled, optionRef: optionRefParam, id: idParam } = params;
 
   const {
-    getOptionProps,
-    getOptionState,
-    listboxRef,
-    registerHighlightChangeHandler,
-    registerSelectionChangeHandler,
-  } = selectContext;
-
-  const optionState = getOptionState(value);
-
-  const { selected, highlighted } = optionState;
-
-  const rerender = useForcedRerendering();
-
-  React.useEffect(() => {
-    function updateSelectedState(selectedValues: Value | Value[] | null) {
-      if (!selected) {
-        if (Array.isArray(selectedValues)) {
-          if (selectedValues.includes(value)) {
-            rerender();
-          }
-        } else if (selectedValues === value) {
-          rerender();
-        }
-      } else if (Array.isArray(selectedValues)) {
-        if (!selectedValues.includes(value)) {
-          rerender();
-        }
-      } else if (selectedValues !== value) {
-        rerender();
-      }
-    }
-
-    return registerSelectionChangeHandler(updateSelectedState);
-  }, [registerSelectionChangeHandler, rerender, selected, value]);
+    getRootProps: getListItemProps,
+    ref: listItemRefHandler,
+    highlighted,
+    selected,
+  } = useListItem({
+    item: value,
+  });
 
-  React.useEffect(() => {
-    function updateHighlightedState(highlightedValue: Value | null) {
-      if (highlightedValue === value && !highlighted) {
-        rerender();
-      } else if (highlightedValue !== value && highlighted) {
-        rerender();
-      }
-    }
+  const id = useId(idParam);
 
-    return registerHighlightChangeHandler(updateHighlightedState);
-  }, [registerHighlightChangeHandler, rerender, value, highlighted]);
+  const optionRef = React.useRef<HTMLElement>(null);
 
-  const optionRef = React.useRef<HTMLLIElement>(null);
-  const handleRef = useForkRef(optionRefParam, optionRef);
+  const selectOption: SelectOption<Value> = React.useMemo(
+    () => ({
+      disabled,
+      label,
+      value,
+      ref: optionRef,
+      id,
+    }),
+    [disabled, label, value, id],
+  );
 
-  React.useEffect(() => {
-    // Scroll to the currently highlighted option
-    if (highlighted) {
-      if (!listboxRef.current || !optionRef.current) {
-        return;
-      }
-      const listboxClientRect = (listboxRef.current as HTMLElement).getBoundingClientRect();
-      const optionClientRect = optionRef.current.getBoundingClientRect();
+  const { index } = useCompoundItem<Value, SelectOption<Value>>(value, selectOption);
 
-      if (optionClientRect.top < listboxClientRect.top) {
-        listboxRef.current.scrollTop -= listboxClientRect.top - optionClientRect.top;
-      } else if (optionClientRect.bottom > listboxClientRect.bottom) {
-        listboxRef.current.scrollTop += optionClientRect.bottom - listboxClientRect.bottom;
-      }
-    }
-  }, [highlighted, listboxRef]);
+  const handleRef = useForkRef(optionRefParam, optionRef, listItemRefHandler);
 
   return {
     getRootProps: <Other extends EventHandlers = {}>(otherHandlers: Other = {} as Other) => ({
       ...otherHandlers,
-      ...getOptionProps(value, otherHandlers),
+      ...getListItemProps(otherHandlers),
+      id,
       ref: handleRef,
+      role: 'option',
+      'aria-selected': selected,
     }),
     highlighted,
-    index: optionState.index,
+    index,
     selected,
   };
 }
diff --git a/packages/mui-base/src/useOption/useOption.types.ts b/packages/mui-base/src/useOption/useOption.types.ts
index e67a42a4ac77e8..5eb0820e383a89 100644
--- a/packages/mui-base/src/useOption/useOption.types.ts
+++ b/packages/mui-base/src/useOption/useOption.types.ts
@@ -1,10 +1,20 @@
-import { UseSelectOptionSlotProps } from '../useSelect';
+import { UseListItemRootSlotProps } from '../useList';
 import { EventHandlers } from '../utils';
 
+export interface SelectOption<Value> {
+  value: Value;
+  label: React.ReactNode;
+  disabled?: boolean;
+  ref: React.RefObject<HTMLElement>;
+  id?: string;
+}
+
 export interface UseOptionParameters<Value> {
   disabled: boolean;
+  label: string | React.ReactNode;
   value: Value;
   optionRef?: React.Ref<HTMLElement>;
+  id?: string;
 }
 
 export interface UseOptionReturnValue {
@@ -16,6 +26,7 @@ export interface UseOptionReturnValue {
   ) => UseOptionRootSlotProps<Other>;
 }
 
-export type UseOptionRootSlotProps<Other extends EventHandlers = {}> = UseSelectOptionSlotProps & {
-  ref?: React.RefCallback<HTMLElement> | null;
-} & Other;
+export type UseOptionRootSlotProps<Other extends EventHandlers = {}> =
+  UseListItemRootSlotProps<Other> & {
+    ref?: React.RefCallback<HTMLElement> | null;
+  } & Other;
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
new file mode 100644
index 00000000000000..9288def502bdd0
--- /dev/null
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -0,0 +1,63 @@
+import * as React from 'react';
+import { ListContext, ListContextValue } from '../useList';
+import { SelectOption } from '../useOption/useOption.types';
+import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+
+export type SelectProviderValue<Value> = CompoundComponentContextValue<Value, SelectOption<Value>> &
+  ListContextValue<Value>;
+
+export interface SelectProviderProps<Value> {
+  value: SelectProviderValue<Value>;
+  children: React.ReactNode;
+}
+
+export default function SelectProvider<Value>(props: SelectProviderProps<Value>) {
+  const { value, children } = props;
+
+  const {
+    dispatch,
+    getItemIndex,
+    getItemState,
+    registerHighlightChangeHandler,
+    registerSelectionChangeHandler,
+    registerItem,
+    unregisterItem,
+    totalSubitemCount,
+  } = value;
+
+  const listContextValue: ListContextValue<Value> = React.useMemo(
+    () => ({
+      dispatch,
+      getItemState,
+      getItemIndex,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    }),
+    [
+      dispatch,
+      getItemIndex,
+      getItemState,
+      registerHighlightChangeHandler,
+      registerSelectionChangeHandler,
+    ],
+  );
+
+  const compoundComponentContextValue: CompoundComponentContextValue<
+    Value,
+    SelectOption<Value>
+  > = React.useMemo(
+    () => ({
+      getItemIndex,
+      registerItem,
+      totalSubitemCount,
+      unregisterItem,
+    }),
+    [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+  );
+
+  return (
+    <CompoundComponentContext.Provider value={compoundComponentContextValue}>
+      <ListContext.Provider value={listContextValue}>{children}</ListContext.Provider>
+    </CompoundComponentContext.Provider>
+  );
+}
diff --git a/packages/mui-base/src/useSelect/index.ts b/packages/mui-base/src/useSelect/index.ts
index b812ca7155b44f..fdf70bd247967a 100644
--- a/packages/mui-base/src/useSelect/index.ts
+++ b/packages/mui-base/src/useSelect/index.ts
@@ -1,2 +1,5 @@
 export { default } from './useSelect';
 export * from './useSelect.types';
+
+export { default as SelectProvider } from './SelectProvider';
+export * from './SelectProvider';
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index f0cc9b14dfe83d..f8dce8821c0ef7 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -1,24 +1,29 @@
 import * as React from 'react';
-import { unstable_useForkRef as useForkRef, unstable_useId as useId } from '@mui/utils';
+import {
+  unstable_useForkRef as useForkRef,
+  unstable_useId as useId,
+  unstable_useEnhancedEffect as useEnhancedEffect,
+} from '@mui/utils';
 import useButton from '../useButton';
 import {
-  SelectOption,
   SelectValue,
   UseSelectButtonSlotProps,
   UseSelectListboxSlotProps,
-  UseSelectOptionSlotProps,
   UseSelectParameters,
   UseSelectResult,
 } from './useSelect.types';
-import useListbox, {
-  ListboxReducer,
+import useList, {
+  ListReducer,
   defaultListboxReducer,
   ActionTypes,
-  UseListboxParameters,
-} from '../useListbox';
+  UseListParameters,
+  ListState,
+} from '../useList';
 import { EventHandlers } from '../utils/types';
 import defaultOptionStringifier from '../SelectUnstyled/defaultOptionStringifier';
-import useSelectChangeNotifiers from './useSelectChangeNotifiers';
+import { SelectProviderValue } from './SelectProvider';
+import { useCompoundParent } from '../utils/useCompound';
+import { SelectOption } from '../useOption/useOption.types';
 
 /**
  *
@@ -44,7 +49,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
     onHighlightChange,
     onOpenChange,
     open = false,
-    options,
+    options: optionsParam,
     optionStringifier = defaultOptionStringifier,
     value: valueProp,
   } = props;
@@ -70,13 +75,29 @@ function useSelect<TValue, Multiple extends boolean = false>(
     return undefined;
   }, [valueProp, multiple]);
 
-  const optionsMap = React.useMemo(() => {
-    const map = new Map<TValue, SelectOption<TValue>>();
-    options.forEach((option) => {
-      map.set(option.value, option);
-    });
-    return map;
-  }, [options]);
+  const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
+    TValue,
+    SelectOption<TValue>
+  >();
+
+  const options = React.useMemo(() => {
+    if (optionsParam != null) {
+      return new Map(
+        optionsParam.map((option, index) => [
+          option.value,
+          {
+            value: option.value,
+            label: option.label,
+            disabled: option.disabled,
+            ref: React.createRef<HTMLElement>(),
+            id: `${listboxId}_${index}`,
+          },
+        ]),
+      );
+    }
+
+    return subitems;
+  }, [optionsParam, subitems, listboxId]);
 
   // prevents closing the listbox on keyUp right after opening it
   const ignoreEnterKeyUp = React.useRef(false);
@@ -97,13 +118,6 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
   const handleListboxRef = useForkRef(listboxRefProp, listboxRef, focusListboxIfRequested);
 
-  const {
-    notifySelectionChanged,
-    notifyHighlightChanged,
-    registerHighlightChangeHandler,
-    registerSelectionChangeHandler,
-  } = useSelectChangeNotifiers<TValue>();
-
   React.useEffect(() => {
     focusListboxIfRequested();
   }, [focusListboxIfRequested]);
@@ -164,20 +178,6 @@ function useSelect<TValue, Multiple extends boolean = false>(
       ignoreEnterKeyUp.current = false;
     };
 
-  const createHandleListboxItemClick = React.useCallback(
-    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.MouseEvent) => {
-      otherHandlers?.onClick?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
-
-      if (!multiple) {
-        onOpenChange?.(false);
-      }
-    },
-    [multiple, onOpenChange],
-  );
-
   const createHandleListboxBlur =
     (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.FocusEvent) => {
       otherHandlers?.onBlur?.(event);
@@ -186,9 +186,9 @@ function useSelect<TValue, Multiple extends boolean = false>(
       }
     };
 
-  const listboxReducer: ListboxReducer<TValue> = React.useCallback(
+  const listboxReducer: ListReducer<TValue> = React.useCallback(
     (state, action) => {
-      const newState = defaultListboxReducer<TValue>(state, action);
+      const newState: ListState<TValue> = defaultListboxReducer<TValue>(state, action);
 
       switch (action.type) {
         case ActionTypes.keyDown:
@@ -208,7 +208,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
         case ActionTypes.blur:
         case ActionTypes.setValue:
-        case ActionTypes.optionsChange:
+        case ActionTypes.itemsChange:
           return {
             ...newState,
             highlightedValue:
@@ -233,33 +233,33 @@ function useSelect<TValue, Multiple extends boolean = false>(
     ref: handleButtonRef,
   });
 
-  const optionValues = React.useMemo(() => options.map((o) => o.value), [options]);
+  const optionValues = React.useMemo(() => Array.from(options.keys()), [options]);
 
-  const isOptionDisabled = React.useCallback(
+  const isItemDisabled = React.useCallback(
     (valueToCheck: TValue) => {
-      const option = optionsMap.get(valueToCheck);
+      const option = options.get(valueToCheck);
       return option?.disabled ?? false;
     },
-    [optionsMap],
+    [options],
   );
 
   const stringifyOption = React.useCallback(
     (valueToCheck: TValue) => {
-      const option = optionsMap.get(valueToCheck);
+      const option = options.get(valueToCheck);
       if (!option) {
         return '';
       }
 
       return optionStringifier(option);
     },
-    [optionsMap, optionStringifier],
+    [options, optionStringifier],
   );
 
-  const useListboxParameters: UseListboxParameters<TValue> = {
+  const useListboxParameters: UseListParameters<TValue> = {
     defaultValue,
-    id: listboxId,
-    isOptionDisabled,
-    listboxRef: handleListboxRef,
+    getItemId: (itemValue) => options.get(itemValue)?.id,
+    isItemDisabled,
+    listRef: handleListboxRef,
     onChange: (e, newValues) => {
       if (multiple) {
         onChange?.(e, newValues as SelectValue<TValue, Multiple>);
@@ -270,8 +270,8 @@ function useSelect<TValue, Multiple extends boolean = false>(
     onHighlightChange: (e, newValue) => {
       onHighlightChange?.(e, newValue ?? null);
     },
-    options: optionValues,
-    optionStringifier: stringifyOption,
+    items: optionValues,
+    itemStringifier: stringifyOption,
     selectionLimit: multiple ? null : 1,
     stateReducer: listboxReducer,
     value,
@@ -279,19 +279,38 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
   const {
     getRootProps: getListboxRootProps,
-    getOptionProps: getListboxOptionProps,
-    getOptionState,
     highlightedOption,
     selectedOptions,
-  } = useListbox(useListboxParameters);
+    contextValue: listContextValue,
+  } = useList(useListboxParameters);
+
+  useEnhancedEffect(() => {
+    // TODO: the listbox should close when an option is clicked (even if it's already selected)
+    // close the listbox when an option is selected
+    if (!multiple && listboxRef.current?.contains(document.activeElement)) {
+      onOpenChange?.(false);
+      buttonRef.current?.focus();
+    }
+  }, [multiple, onOpenChange, selectedOptions]);
 
-  React.useEffect(() => {
-    notifySelectionChanged(selectedOptions);
-  }, [selectedOptions, notifySelectionChanged]);
+  useEnhancedEffect(() => {
+    // Scroll to the currently highlighted option.
+    if (highlightedOption != null) {
+      const optionRef = options.get(highlightedOption)?.ref;
+      if (!listboxRef.current || !optionRef?.current) {
+        return;
+      }
 
-  React.useEffect(() => {
-    notifyHighlightChanged(highlightedOption);
-  }, [highlightedOption, notifyHighlightChanged]);
+      const listboxClientRect = (listboxRef.current as HTMLElement).getBoundingClientRect();
+      const optionClientRect = optionRef.current.getBoundingClientRect();
+
+      if (optionClientRect.top < listboxClientRect.top) {
+        listboxRef.current.scrollTop -= listboxClientRect.top - optionClientRect.top;
+      } else if (optionClientRect.bottom > listboxClientRect.bottom) {
+        listboxRef.current.scrollTop += optionClientRect.bottom - listboxClientRect.bottom;
+      }
+    }
+  }, [highlightedOption, options]);
 
   const getButtonProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
@@ -310,27 +329,25 @@ function useSelect<TValue, Multiple extends boolean = false>(
     };
   };
 
+  const getOptionMetadata = React.useCallback(
+    (optionValue: TValue) => options.get(optionValue),
+    [options],
+  );
+
   const getListboxProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
-  ): UseSelectListboxSlotProps<TOther> =>
-    getListboxRootProps({
-      ...otherHandlers,
-      onBlur: createHandleListboxBlur(otherHandlers),
-      onKeyUp: createHandleListboxKeyUp(otherHandlers),
-    });
-
-  const getOptionProps = React.useCallback(
-    <TOther extends EventHandlers>(
-      optionValue: TValue,
-      otherHandlers: TOther = {} as TOther,
-    ): UseSelectOptionSlotProps<TOther> => {
-      return getListboxOptionProps(optionValue, {
+  ): UseSelectListboxSlotProps<TOther> => {
+    return {
+      ...getListboxRootProps({
         ...otherHandlers,
-        onClick: createHandleListboxItemClick(otherHandlers),
-      });
-    },
-    [getListboxOptionProps, createHandleListboxItemClick],
-  );
+        onBlur: createHandleListboxBlur(otherHandlers),
+        onKeyUp: createHandleListboxKeyUp(otherHandlers),
+      }),
+      id: listboxId,
+      role: 'listbox' as const,
+      'aria-multiselectable': multiple ? 'true' : undefined,
+    };
+  };
 
   React.useDebugValue({
     selectedOptions,
@@ -338,20 +355,12 @@ function useSelect<TValue, Multiple extends boolean = false>(
     open,
   });
 
-  const contextValue = React.useMemo(
+  const contextValue: SelectProviderValue<TValue> = React.useMemo(
     () => ({
-      listboxRef,
-      getOptionProps,
-      getOptionState,
-      registerHighlightChangeHandler,
-      registerSelectionChangeHandler,
+      ...listContextValue,
+      ...compoundComponentContextValue,
     }),
-    [
-      getOptionProps,
-      getOptionState,
-      registerHighlightChangeHandler,
-      registerSelectionChangeHandler,
-    ],
+    [listContextValue, compoundComponentContextValue],
   );
 
   if (props.multiple) {
@@ -361,8 +370,10 @@ function useSelect<TValue, Multiple extends boolean = false>(
       disabled,
       getButtonProps,
       getListboxProps,
+      getOptionMetadata,
       contextValue,
       open,
+      options: optionValues,
       value: selectedOptions as SelectValue<TValue, Multiple>,
       highlightedOption,
     };
@@ -374,8 +385,10 @@ function useSelect<TValue, Multiple extends boolean = false>(
     disabled,
     getButtonProps,
     getListboxProps,
+    getOptionMetadata,
     contextValue,
     open,
+    options: optionValues,
     value: (selectedOptions.length > 0 ? selectedOptions[0] : null) as SelectValue<
       TValue,
       Multiple
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 8e8c4d69a764c3..b1acddc153e675 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -1,28 +1,9 @@
 import * as React from 'react';
 import { UseButtonRootSlotProps } from '../useButton';
-import { OptionState, UseListboxOptionSlotProps, UseListboxRootSlotProps } from '../useListbox';
+import { UseListRootSlotProps } from '../useList';
+import { SelectOption } from '../useOption/useOption.types';
 import { EventHandlers } from '../utils/types';
-import { SelectChangeNotifiers } from './useSelectChangeNotifiers';
-
-export interface SelectOption<TValue> {
-  value: TValue;
-  label: React.ReactNode;
-  disabled?: boolean;
-}
-
-export interface SelectOptionGroup<TValue> {
-  options: SelectChild<TValue>[];
-  label: React.ReactNode;
-  disabled?: boolean;
-}
-
-export type SelectChild<TValue> = SelectOption<TValue> | SelectOptionGroup<TValue>;
-
-export function isOptionGroup<TValue>(
-  child: SelectChild<TValue>,
-): child is SelectOptionGroup<TValue> {
-  return !!(child as SelectOptionGroup<TValue>).options;
-}
+import { SelectProviderValue } from './SelectProvider';
 
 export type SelectChangeEventType =
   | React.MouseEvent<Element, MouseEvent>
@@ -32,6 +13,12 @@ export type SelectChangeEventType =
 
 export type SelectValue<Value, Multiple> = Multiple extends true ? Value[] : Value | null;
 
+export interface SelectOptionDefinition<Value> {
+  value: Value;
+  disabled?: boolean;
+  label: string;
+}
+
 export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
   defaultValue?: SelectValue<TValue, Multiple>;
   disabled?: boolean;
@@ -53,7 +40,7 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
   ) => void;
   onOpenChange?: (open: boolean) => void;
   open?: boolean;
-  options: SelectOption<TValue>[];
+  options?: SelectOptionDefinition<TValue>[];
   optionStringifier?: (option: SelectOption<TValue>) => string;
   value?: SelectValue<TValue, Multiple>;
 };
@@ -76,18 +63,10 @@ interface UseSelectListboxSlotEventHandlers {
   onKeyUp: React.KeyboardEventHandler;
 }
 
-export type UseSelectListboxSlotProps<TOther = {}> = UseListboxRootSlotProps<
+export type UseSelectListboxSlotProps<TOther = {}> = UseListRootSlotProps<
   Omit<TOther, keyof UseSelectListboxSlotEventHandlers> & UseSelectListboxSlotEventHandlers
 >;
 
-interface UseSelectOptionSlotEventHandlers {
-  onClick: React.MouseEventHandler;
-}
-
-export type UseSelectOptionSlotProps<TOther = {}> = UseListboxOptionSlotProps<
-  Omit<TOther, keyof UseSelectOptionSlotEventHandlers> & UseSelectOptionSlotEventHandlers
->;
-
 export interface UseSelectResult<TValue, Multiple> {
   buttonActive: boolean;
   buttonFocusVisible: boolean;
@@ -98,25 +77,10 @@ export interface UseSelectResult<TValue, Multiple> {
   getListboxProps: <TOther extends EventHandlers = {}>(
     otherHandlers?: TOther,
   ) => UseSelectListboxSlotProps<TOther>;
-  contextValue: {
-    getOptionProps: <TOther extends EventHandlers = {}>(
-      option: TValue,
-      otherHandlers?: TOther,
-    ) => UseSelectOptionSlotProps<TOther>;
-    getOptionState: (option: TValue) => OptionState;
-    listboxRef: React.RefObject<HTMLElement>;
-    /**
-     * Registers a handler for when the highlighted option changes.
-     * @param handler A function that will be called with the new highlighted option.
-     */
-    registerHighlightChangeHandler: SelectChangeNotifiers<TValue>['registerHighlightChangeHandler'];
-    /**
-     * Registers a handler for when the selection changes.
-     * @param handler A function that will be called with the new selected items.
-     */
-    registerSelectionChangeHandler: SelectChangeNotifiers<TValue>['registerSelectionChangeHandler'];
-  };
+  getOptionMetadata: (option: TValue) => SelectOption<TValue> | undefined;
+  contextValue: SelectProviderValue<TValue>;
   highlightedOption: TValue | null;
   open: boolean;
+  options: TValue[];
   value: SelectValue<TValue, Multiple>;
 }
diff --git a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.test.tsx b/packages/mui-base/src/useSelect/useSelectChangeNotifiers.test.tsx
deleted file mode 100644
index f9300855ed9d6b..00000000000000
--- a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.test.tsx
+++ /dev/null
@@ -1,121 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { spy } from 'sinon';
-import { act, render } from 'test/utils';
-import useSelectChangeNotifiers from './useSelectChangeNotifiers';
-
-describe('useSelectChangeNotifiers', () => {
-  it('should call the registered handler when the value changes', () => {
-    const handler = spy();
-
-    function TestComponent() {
-      const { registerSelectionChangeHandler, notifySelectionChanged } = useSelectChangeNotifiers();
-      registerSelectionChangeHandler(handler);
-      const [value, setValue] = React.useState(0);
-
-      const handleClick = () => {
-        setValue((v) => v + 1);
-        notifySelectionChanged(value + 1);
-      };
-
-      return <button onClick={handleClick}>Update selection</button>;
-    }
-
-    const { getByRole } = render(<TestComponent />);
-    const button = getByRole('button');
-
-    act(() => {
-      button.click();
-    });
-
-    expect(handler.callCount).to.equal(1);
-    expect(handler.args[0][0]).to.equal(1);
-  });
-
-  it('should call the registered handler when the highlight changes', () => {
-    const handler = spy();
-
-    function TestComponent() {
-      const { registerHighlightChangeHandler, notifyHighlightChanged } = useSelectChangeNotifiers();
-      registerHighlightChangeHandler(handler);
-      const [value, setValue] = React.useState(0);
-
-      const handleClick = () => {
-        setValue((v) => v + 1);
-        notifyHighlightChanged(value + 1);
-      };
-
-      return <button onClick={handleClick}>Update highlight</button>;
-    }
-
-    const { getByRole } = render(<TestComponent />);
-    const button = getByRole('button');
-
-    act(() => {
-      button.click();
-    });
-
-    expect(handler.callCount).to.equal(1);
-    expect(handler.args[0][0]).to.equal(1);
-  });
-
-  it('should not call the handlers after they are unregistered', () => {
-    const changeHandler = spy();
-    const highlightChangeHandler = spy();
-
-    function TestComponent() {
-      const {
-        notifySelectionChanged,
-        notifyHighlightChanged,
-        registerSelectionChangeHandler,
-        registerHighlightChangeHandler,
-      } = useSelectChangeNotifiers();
-
-      const unregisterSelectionChangeHandler = registerSelectionChangeHandler(changeHandler);
-      const unregisterHighlightChangeHandler =
-        registerHighlightChangeHandler(highlightChangeHandler);
-
-      const [value, setValue] = React.useState(0);
-
-      const updateValue = () => {
-        setValue((v) => v + 1);
-        notifySelectionChanged(value + 1);
-        notifyHighlightChanged(value + 1);
-      };
-
-      const clearHandlers = () => {
-        unregisterSelectionChangeHandler();
-        unregisterHighlightChangeHandler();
-      };
-
-      return (
-        <div>
-          <button onClick={updateValue}>Update selection</button>
-          <button onClick={clearHandlers}>Clear handlers</button>
-        </div>
-      );
-    }
-
-    const { getByText } = render(<TestComponent />);
-    const updateButton = getByText('Update selection');
-    const clearButton = getByText('Clear handlers');
-
-    act(() => {
-      updateButton.click();
-    });
-
-    expect(changeHandler.callCount).to.equal(1);
-    expect(highlightChangeHandler.callCount).to.equal(1);
-
-    act(() => {
-      clearButton.click();
-    });
-
-    act(() => {
-      updateButton.click();
-    });
-
-    expect(changeHandler.callCount).to.equal(1);
-    expect(highlightChangeHandler.callCount).to.equal(1);
-  });
-});
diff --git a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts b/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts
deleted file mode 100644
index 5c717d80aafb3c..00000000000000
--- a/packages/mui-base/src/useSelect/useSelectChangeNotifiers.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import * as React from 'react';
-import useMessageBus from '../utils/useMessageBus';
-
-const SELECTION_CHANGE_TOPIC = Symbol('select:change-selection');
-const HIGHLIGHT_CHANGE_TOPIC = Symbol('select:change-highlight');
-
-export interface SelectChangeNotifiers<TValue> {
-  /**
-   * Calls all the registered selection change handlers.
-   *
-   * @param newValue - The newly selected value(s).
-   */
-  notifySelectionChanged: (newValue: TValue | TValue[] | null) => void;
-  /**
-   * Calls all the registered highlight change handlers.
-   *
-   * @param newValue - The newly highlighted value.
-   */
-  notifyHighlightChanged: (newValue: TValue | null) => void;
-
-  registerSelectionChangeHandler: (
-    handler: (newValue: TValue | TValue[] | null) => void,
-  ) => () => void;
-
-  registerHighlightChangeHandler: (handler: (newValue: TValue | null) => void) => () => void;
-}
-
-/**
- * @ignore - internal hook.
- *
- * This hook is used to notify any interested components about changes in the Select's selection and highlight.
- */
-export default function useSelectChangeNotifiers<TValue>(): SelectChangeNotifiers<TValue> {
-  const messageBus = useMessageBus();
-
-  const notifySelectionChanged = React.useCallback(
-    (newValue: TValue | TValue[] | null) => {
-      messageBus.publish(SELECTION_CHANGE_TOPIC, newValue);
-    },
-    [messageBus],
-  );
-
-  const notifyHighlightChanged = React.useCallback(
-    (newValue: TValue | null) => {
-      messageBus.publish(HIGHLIGHT_CHANGE_TOPIC, newValue);
-    },
-    [messageBus],
-  );
-
-  const registerSelectionChangeHandler = React.useCallback(
-    (handler: (newValue: TValue | TValue[] | null) => void) => {
-      return messageBus.subscribe(SELECTION_CHANGE_TOPIC, handler);
-    },
-    [messageBus],
-  );
-
-  const registerHighlightChangeHandler = React.useCallback(
-    (handler: (newValue: TValue | null) => void) => {
-      return messageBus.subscribe(HIGHLIGHT_CHANGE_TOPIC, handler);
-    },
-    [messageBus],
-  );
-
-  return {
-    notifySelectionChanged,
-    notifyHighlightChanged,
-    registerSelectionChangeHandler,
-    registerHighlightChangeHandler,
-  };
-}
diff --git a/packages/mui-joy/src/Select/SelectProps.ts b/packages/mui-joy/src/Select/SelectProps.ts
index e16b3b5f337830..37f7aa57d992f0 100644
--- a/packages/mui-joy/src/Select/SelectProps.ts
+++ b/packages/mui-joy/src/Select/SelectProps.ts
@@ -1,11 +1,11 @@
 import * as React from 'react';
 import { OverridableStringUnion, OverrideProps } from '@mui/types';
 import { PopperUnstyledOwnProps } from '@mui/base/PopperUnstyled';
-import { SelectOption } from '@mui/base/useSelect';
+import { SelectOption } from '@mui/base/useOption';
 import { ColorPaletteProp, SxProps, VariantProp, ApplyColorInversion } from '../styles/types';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
-export type { SelectOption } from '@mui/base/useSelect';
+export type { SelectOption } from '@mui/base/useOption';
 
 export type SelectSlot =
   | 'root'

From 319985b5997d7a4d8eb8dd979d513e1bcb4f74dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 23 Mar 2023 10:04:36 +0100
Subject: [PATCH 08/49] Decouple the controllableReducer from the List

---
 .../src/MenuUnstyled/MenuUnstyled.tsx         |  10 +-
 .../src/MenuUnstyled/MenuUnstyled.types.ts    |   5 +-
 .../SelectUnstyled/SelectUnstyled.test.tsx    |   6 +-
 .../mui-base/src/useList/actions.types.ts     |  66 ++-
 .../src/useList/defaultListboxReducer.test.ts | 403 ++++++++++--------
 .../src/useList/defaultListboxReducer.ts      |  75 ++--
 .../useList/useControllableReducer.test.tsx   | 162 -------
 .../src/useList/useControllableReducer.ts     | 156 -------
 packages/mui-base/src/useList/useList.ts      | 134 ++++--
 .../mui-base/src/useList/useList.types.ts     |  86 ++--
 .../mui-base/src/useMenu/MenuProvider.tsx     |   5 +-
 packages/mui-base/src/useMenu/useMenu.ts      | 159 +++----
 .../mui-base/src/useMenu/useMenu.types.ts     |  10 +-
 .../mui-base/src/useSelect/SelectProvider.tsx |   5 +-
 packages/mui-base/src/useSelect/useSelect.ts  | 252 +++++++----
 .../mui-base/src/useSelect/useSelect.types.ts |  26 +-
 .../src/useTabsList/TabsListProvider.tsx      |   9 +-
 .../mui-base/src/useTabsList/useTabsList.ts   |  48 ++-
 .../src/utils/useControllableReducer.test.tsx | 325 ++++++++++++++
 .../src/utils/useControllableReducer.ts       | 168 ++++++++
 .../src/utils/useControllableReducer.types.ts |  73 ++++
 packages/mui-base/src/utils/useLatest.ts      |   1 +
 22 files changed, 1359 insertions(+), 825 deletions(-)
 delete mode 100644 packages/mui-base/src/useList/useControllableReducer.test.tsx
 delete mode 100644 packages/mui-base/src/useList/useControllableReducer.ts
 create mode 100644 packages/mui-base/src/utils/useControllableReducer.test.tsx
 create mode 100644 packages/mui-base/src/utils/useControllableReducer.ts
 create mode 100644 packages/mui-base/src/utils/useControllableReducer.types.ts

diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
index 7c453a9c97d501..c9005c48bfdaad 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
@@ -43,18 +43,20 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
     anchorEl,
     children,
     component,
+    defaultOpen,
     keepMounted = false,
     listboxId,
-    onClose,
-    open = false,
+    onOpenChange,
+    open,
     slotProps = {},
     slots = {},
     ...other
   } = props;
 
   const { contextValue, getListboxProps, highlightFirstItem, highlightLastItem } = useMenu({
+    defaultOpen,
     open,
-    onClose,
+    onOpenChange,
     listboxId,
   });
 
@@ -69,7 +71,7 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
 
   const ownerState: MenuUnstyledOwnerState = {
     ...props,
-    open,
+    keepMounted,
   };
 
   const classes = useUtilityClasses(ownerState);
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
index 9d5c3de8be473b..f5ec8b9feb0607 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
@@ -26,6 +26,7 @@ export interface MenuUnstyledOwnProps {
   anchorEl?: PopperUnstyledProps['anchorEl'];
   children?: React.ReactNode;
   className?: string;
+  defaultOpen?: boolean;
   /**
    * Always keep the menu in the DOM.
    * This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.
@@ -37,7 +38,7 @@ export interface MenuUnstyledOwnProps {
   /**
    * Triggered when focus leaves the menu and the menu should close.
    */
-  onClose?: () => void;
+  onOpenChange?: (open: boolean) => void;
   /**
    * Controls whether the menu is displayed.
    * @default false
@@ -92,7 +93,7 @@ export type MenuUnstyledProps<
 };
 
 export interface MenuUnstyledOwnerState extends MenuUnstyledOwnProps {
-  open: boolean;
+  keepMounted: boolean;
 }
 
 export type MenuUnstyledRootSlotProps = {
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index 5ada0e043f8584..0036d431dc27fe 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -96,7 +96,7 @@ describe('<SelectUnstyled />', () => {
         });
 
         const listbox = getByRole('listbox');
-        userEvent.keyPress(listbox, { key });
+        fireEvent.keyDown(listbox, { key });
 
         expect(select).to.have.attribute('aria-expanded', 'false');
         expect(listbox).not.toBeVisible();
@@ -351,8 +351,8 @@ describe('<SelectUnstyled />', () => {
       });
 
       const listbox = getByRole('listbox');
-      userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '2'
-      userEvent.keyPress(listbox, { key: 'Escape' });
+      fireEvent.keyDown(listbox, { key: 'ArrowDown' }); // highlights '2'
+      fireEvent.keyDown(listbox, { key: 'Escape' });
 
       expect(select).to.have.attribute('aria-expanded', 'false');
       expect(select).to.have.text('1');
diff --git a/packages/mui-base/src/useList/actions.types.ts b/packages/mui-base/src/useList/actions.types.ts
index 14244219272452..4a6f5547c9950a 100644
--- a/packages/mui-base/src/useList/actions.types.ts
+++ b/packages/mui-base/src/useList/actions.types.ts
@@ -1,77 +1,63 @@
-enum ActionTypes {
-  blur = 'blur',
-  focus = 'focus',
-  keyDown = 'keyDown',
-  itemClick = 'itemClick',
-  itemHover = 'itemHover',
-  itemsChange = 'itemsChange',
-  setValue = 'setValue',
-  setHighlight = 'setHighlight',
-  textNavigation = 'textNagivation',
-}
-
-// split declaration and export due to https://github.com/codesandbox/codesandbox-client/issues/6435
-export { ActionTypes };
+import { SetStateAction, setStateActionType } from '../utils/useControllableReducer.types';
+import type { ListState } from './useList.types';
+
+export const ActionTypes = {
+  blur: 'blur',
+  focus: 'focus',
+  keyDown: 'keyDown',
+  itemClick: 'itemClick',
+  itemHover: 'itemHover',
+  itemsChange: 'itemsChange',
+  setState: setStateActionType,
+  textNavigation: 'textNavigation',
+} as const;
 
 interface ItemClickAction<Value> {
-  type: ActionTypes.itemClick;
+  type: typeof ActionTypes.itemClick;
   item: Value;
   event: React.MouseEvent;
 }
 
 interface ItemHoverAction<Value> {
-  type: ActionTypes.itemHover;
+  type: typeof ActionTypes.itemHover;
   item: Value;
   event: React.MouseEvent;
 }
 
 interface FocusAction {
-  type: ActionTypes.focus;
+  type: typeof ActionTypes.focus;
   event: React.FocusEvent;
 }
 
 interface BlurAction {
-  type: ActionTypes.blur;
+  type: typeof ActionTypes.blur;
   event: React.FocusEvent;
 }
 
 interface KeyDownAction {
-  type: ActionTypes.keyDown;
+  type: typeof ActionTypes.keyDown;
   event: React.KeyboardEvent;
 }
 
-interface SetValueAction<Value> {
-  type: ActionTypes.setValue;
-  event: null;
-  values: Value[];
-}
-
-interface SetHighlightAction<Value> {
-  type: ActionTypes.setHighlight;
-  event: null;
-  value: Value | null;
-}
-
 interface TextNavigationAction {
-  type: ActionTypes.textNavigation;
+  type: typeof ActionTypes.textNavigation;
   event: React.KeyboardEvent;
   searchString: string;
 }
 
 interface ItemsChangeAction<Value> {
-  type: ActionTypes.itemsChange;
+  type: typeof ActionTypes.itemsChange;
   event: null;
   items: Value[];
   previousItems: Value[];
 }
 
-export type ListAction<Value> =
+export type ListAction<Value, State extends ListState<Value>> =
+  | BlurAction
+  | FocusAction
   | ItemClickAction<Value>
   | ItemHoverAction<Value>
-  | FocusAction
-  | BlurAction
+  | ItemsChangeAction<Value>
   | KeyDownAction
-  | SetHighlightAction<Value>
-  | TextNavigationAction
-  | SetValueAction<Value>
-  | ItemsChangeAction<Value>;
+  | SetStateAction<State>
+  | TextNavigationAction;
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.test.ts b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
index 222d1c718df852..6396990767aa48 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
@@ -12,19 +12,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
-        type: ActionTypes.setValue,
-        values: ['foo'],
+      const action: ListReducerAction<string, ListState<string>> = {
+        type: ActionTypes.setState,
+        value: { selectedValues: ['foo'] },
         event: null,
         props: {
-          items: ['foo', 'bar'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['foo', 'bar'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
       const result = defaultReducer(state, action);
@@ -39,18 +42,21 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.blur,
         event: {} as any, // not relevant
         props: {
-          items: [],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: [],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
@@ -66,18 +72,21 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
         item: 'two',
       };
@@ -92,18 +101,21 @@ describe('useListbox defaultReducer', () => {
         selectedValues: ['one'],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: 1,
+          current: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: 1,
+          },
         },
         item: 'two',
       };
@@ -118,18 +130,21 @@ describe('useListbox defaultReducer', () => {
         selectedValues: ['one'],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
         item: 'two',
       };
@@ -144,18 +159,21 @@ describe('useListbox defaultReducer', () => {
         selectedValues: ['one', 'two'],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
-          items: ['one', 'two', 'three'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
         item: 'two',
       };
@@ -173,20 +191,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Home',
           } as any,
           props: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: (_, index) => index === 0,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three', 'four', 'five'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: (_, index) => index === 0,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -202,20 +223,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'End',
           } as any,
           props: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: (_, index) => index === 4,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three', 'four', 'five'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: (_, index) => index === 4,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -231,20 +255,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowUp',
           } as any,
           props: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: (_, index) => index === 0 || index === 4,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three', 'four', 'five'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: (_, index) => index === 0 || index === 4,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -260,20 +287,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
           props: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: (_, index) => index === 0 || index === 4,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three', 'four', 'five'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: (_, index) => index === 0 || index === 4,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -287,20 +317,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
           props: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: () => true,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three', 'four', 'five'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: () => true,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -316,20 +349,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: () => false,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
         };
 
@@ -343,20 +379,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: ['one'],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: 1,
+            current: {
+              items: ['one', 'two', 'three'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: () => false,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: 1,
+            },
           },
         };
 
@@ -370,20 +409,23 @@ describe('useListbox defaultReducer', () => {
           selectedValues: ['one'],
         };
 
-        const action: ListReducerAction<string> = {
+        const action: ListReducerAction<string, ListState<string>> = {
           type: ActionTypes.itemClick,
           event: {
             key: 'Enter',
           } as any,
           props: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            selectionLimit: null,
+            current: {
+              items: ['one', 'two', 'three'],
+              disableListWrap: false,
+              disabledItemsFocusable: false,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: () => false,
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              selectionLimit: null,
+            },
           },
           item: 'two',
         };
@@ -401,19 +443,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.textNavigation,
         searchString: 'th',
         event: {} as React.KeyboardEvent,
         props: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three', 'four', 'five'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
@@ -427,19 +472,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.textNavigation,
         searchString: 'z',
         event: {} as React.KeyboardEvent,
         props: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three', 'four', 'five'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
@@ -453,19 +501,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          isItemDisabled: (_, i) => i === 1,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three', 'four', 'five'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: (_, i) => i === 1,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
@@ -479,19 +530,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: false,
-          disabledItemsFocusable: true,
-          isItemDisabled: (_, i) => i === 1,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three', 'four', 'five'],
+            disableListWrap: false,
+            disabledItemsFocusable: true,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: (_, i) => i === 1,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
@@ -505,19 +559,22 @@ describe('useListbox defaultReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string> = {
+      const action: ListReducerAction<string, ListState<string>> = {
         type: ActionTypes.textNavigation,
         searchString: 'one',
         event: {} as React.KeyboardEvent,
         props: {
-          items: ['one', 'two', 'three', 'four', 'five'],
-          disableListWrap: true,
-          disabledItemsFocusable: false,
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          selectionLimit: null,
+          current: {
+            items: ['one', 'two', 'three', 'four', 'five'],
+            disableListWrap: true,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: null,
+          },
         },
       };
 
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.ts b/packages/mui-base/src/useList/defaultListboxReducer.ts
index 280cc230729ef3..3be1fae35cc1c3 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.ts
@@ -1,6 +1,11 @@
 import * as React from 'react';
 import { ActionTypes } from './actions.types';
-import { ListState, UseListParametersWithDefaults, ListReducerAction } from './useList.types';
+import {
+  ListState,
+  UseListParametersWithDefaults,
+  ListReducerAction,
+  ListActionAddOn,
+} from './useList.types';
 
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
@@ -178,11 +183,11 @@ function toggleSelection<ItemValue>(
   return newSelection;
 }
 
-function handleItemSelection<ItemValue>(
+function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
   item: ItemValue,
-  state: ListState<ItemValue>,
+  state: State,
   props: UseListParametersWithDefaults<ItemValue>,
-): ListState<ItemValue> {
+): State {
   const { itemComparer = (o, v) => o === v, isItemDisabled = () => false, selectionLimit } = props;
   const { selectedValues } = state;
 
@@ -196,16 +201,17 @@ function handleItemSelection<ItemValue>(
   const newSelectedValues = toggleSelection(item, selectedValues, selectionLimit, itemComparer);
 
   return {
+    ...state,
     selectedValues: newSelectedValues,
     highlightedValue: item,
   };
 }
 
-function handleKeyDown<ItemValue>(
+function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
   event: React.KeyboardEvent,
-  state: Readonly<ListState<ItemValue>>,
+  state: State,
   parameters: UseListParametersWithDefaults<ItemValue>,
-): ListState<ItemValue> {
+): State {
   const previouslySelectedValue = state.highlightedValue;
   const { orientation } = parameters;
 
@@ -295,10 +301,10 @@ function handleKeyDown<ItemValue>(
   return state;
 }
 
-function handleBlur<ItemValue>(
-  state: ListState<ItemValue>,
+function handleBlur<ItemValue, State extends ListState<ItemValue>>(
+  state: State,
   props: UseListParametersWithDefaults<ItemValue>,
-): ListState<ItemValue> {
+): State {
   if (props.focusManagement === 'DOM') {
     return state;
   }
@@ -309,11 +315,11 @@ function handleBlur<ItemValue>(
   };
 }
 
-const textCriteriaMatches = <ItemValue>(
+function textCriteriaMatches<ItemValue>(
   nextFocus: ItemValue,
   searchString: string,
   stringifyItem: (item: ItemValue) => string | undefined,
-) => {
+) {
   const text = stringifyItem(nextFocus)?.trim().toLowerCase();
 
   if (!text || text.length === 0) {
@@ -322,13 +328,13 @@ const textCriteriaMatches = <ItemValue>(
   }
 
   return text.indexOf(searchString) === 0;
-};
+}
 
-function handleTextNavigation<ItemValue>(
-  state: ListState<ItemValue>,
+function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
+  state: State,
   searchString: string,
   props: UseListParametersWithDefaults<ItemValue>,
-): ListState<ItemValue> {
+): State {
   const {
     items,
     isItemDisabled,
@@ -385,12 +391,12 @@ function handleTextNavigation<ItemValue>(
   return state;
 }
 
-function handleItemsChange<ItemValue>(
+function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
   items: ItemValue[],
   previousItems: ItemValue[],
-  state: ListState<ItemValue>,
+  state: State,
   props: UseListParametersWithDefaults<ItemValue>,
-): ListState<ItemValue> {
+): State {
   const { itemComparer, focusManagement } = props;
 
   let newHighlightedValue: ItemValue | null = null;
@@ -409,38 +415,35 @@ function handleItemsChange<ItemValue>(
   );
 
   return {
+    ...state,
     highlightedValue: newHighlightedValue,
     selectedValues: newSelectedValues,
   };
 }
 
-export default function defaultListboxReducer<ItemValue>(
-  state: Readonly<ListState<ItemValue>>,
-  action: ListReducerAction<ItemValue>,
-): Readonly<ListState<ItemValue>> {
-  const { type } = action;
+export default function defaultListboxReducer<ItemValue, State extends ListState<ItemValue>>(
+  state: State,
+  action: ListReducerAction<ItemValue, State> & ListActionAddOn<ItemValue>,
+): State {
+  const { type, props } = action;
+  const parameters = props.current!;
 
   switch (type) {
     case ActionTypes.keyDown:
-      return handleKeyDown(action.event, state, action.props);
+      return handleKeyDown(action.event, state, parameters);
     case ActionTypes.itemClick:
-      return handleItemSelection(action.item, state, action.props);
+      return handleItemSelection(action.item, state, parameters);
     case ActionTypes.blur:
-      return handleBlur(state, action.props);
-    case ActionTypes.setValue:
-      return {
-        ...state,
-        selectedValues: action.values,
-      };
-    case ActionTypes.setHighlight:
+      return handleBlur(state, parameters);
+    case ActionTypes.setState:
       return {
         ...state,
-        highlightedValue: action.value,
+        ...action.value,
       };
     case ActionTypes.textNavigation:
-      return handleTextNavigation(state, action.searchString, action.props);
+      return handleTextNavigation(state, action.searchString, parameters);
     case ActionTypes.itemsChange:
-      return handleItemsChange(action.items, action.previousItems, state, action.props);
+      return handleItemsChange(action.items, action.previousItems, state, parameters);
     default:
       return state;
   }
diff --git a/packages/mui-base/src/useList/useControllableReducer.test.tsx b/packages/mui-base/src/useList/useControllableReducer.test.tsx
deleted file mode 100644
index 90682917a4aa2c..00000000000000
--- a/packages/mui-base/src/useList/useControllableReducer.test.tsx
+++ /dev/null
@@ -1,162 +0,0 @@
-import { expect } from 'chai';
-import * as React from 'react';
-import { spy } from 'sinon';
-import { createRenderer } from 'test/utils';
-import { ActionTypes, ListAction } from './actions.types';
-import { ListState, UseListParametersWithDefaults } from './useList.types';
-import useControllableReducer from './useControllableReducer';
-
-describe('useControllableReducer', () => {
-  const { render } = createRenderer();
-
-  describe('dispatch', () => {
-    it('calls the provided internal reducer', () => {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const reducer = spy((state: ListState<string>, action: ListAction<string>) => {
-        return state;
-      });
-
-      const actionToDispatch = { type: ActionTypes.setValue as const, values: ['b'], event: null };
-      const props: UseListParametersWithDefaults<string> = {
-        items: ['a', 'b', 'c'],
-        defaultValue: ['a'],
-        isItemDisabled: () => false,
-        disableListWrap: false,
-        disabledItemsFocusable: false,
-        itemComparer: (a, b) => a === b,
-        itemStringifier: (item) => item,
-        orientation: 'vertical',
-        selectionLimit: null,
-      };
-
-      function TestComponent() {
-        const [, dispatch] = useControllableReducer(reducer, undefined, { current: props });
-        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
-        return null;
-      }
-
-      render(<TestComponent />);
-      expect(reducer.getCalls()[0].args[1]).to.deep.equal({ ...actionToDispatch, props });
-    });
-
-    it('calls the provided external reducer', () => {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const internalReducer = spy((state: ListState<string>, action: ListAction<string>) => {
-        return state;
-      });
-
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const externalReducer = spy((state: ListState<string>, action: ListAction<string>) => {
-        return state;
-      });
-
-      const actionToDispatch = { type: ActionTypes.setValue as const, values: ['b'], event: null };
-      const props: UseListParametersWithDefaults<string> = {
-        items: ['a', 'b', 'c'],
-        defaultValue: ['a'],
-        isItemDisabled: () => false,
-        disableListWrap: false,
-        disabledItemsFocusable: false,
-        itemComparer: (a, b) => a === b,
-        itemStringifier: (item) => item,
-        orientation: 'vertical',
-        selectionLimit: null,
-      };
-
-      function TestComponent() {
-        const [, dispatch] = useControllableReducer(internalReducer, externalReducer, {
-          current: props,
-        });
-        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
-        return null;
-      }
-
-      render(<TestComponent />);
-      expect(internalReducer.notCalled).to.equal(true);
-      expect(externalReducer.getCalls()[0].args[1]).to.deep.equal({ ...actionToDispatch, props });
-    });
-
-    it('calls onChange when the reducer returns a modified selected value', () => {
-      const reducer = spy((state: ListState<string>) => {
-        return {
-          ...state,
-          selectedValues: ['b'],
-        };
-      });
-
-      const actionToDispatch = {
-        type: ActionTypes.keyDown as const,
-        event: null as unknown as React.KeyboardEvent, // not relevant here
-      };
-      const handleChange = spy();
-      const handleHighlightChange = spy();
-
-      function TestComponent() {
-        const props: UseListParametersWithDefaults<string> = {
-          items: ['a', 'b', 'c'],
-          defaultValue: ['a'],
-          isItemDisabled: () => false,
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          itemComparer: (a, b) => a === b,
-          itemStringifier: (item) => item,
-          onChange: handleChange,
-          onHighlightChange: handleHighlightChange,
-          orientation: 'vertical',
-          selectionLimit: null,
-        };
-
-        const propsRef = React.useRef(props);
-        const [, dispatch] = useControllableReducer(reducer, undefined, propsRef);
-        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
-        return null;
-      }
-
-      render(<TestComponent />);
-      expect(handleChange.called).to.equal(true);
-      expect(handleChange.getCalls()[0].args[1]).to.deep.equal(['b']);
-      expect(handleHighlightChange.notCalled).to.equal(true);
-    });
-
-    it('calls onHighlightChange when the reducer returns a modified highlighted value', () => {
-      const reducer = spy((state: ListState<string>) => {
-        return {
-          ...state,
-          highlightedValue: 'b',
-        };
-      });
-
-      const actionToDispatch = {
-        type: ActionTypes.keyDown as const,
-        event: null as unknown as React.KeyboardEvent, // not relevant here
-      };
-      const handleChange = spy();
-      const handleHighlightChange = spy();
-
-      function TestComponent() {
-        const props: UseListParametersWithDefaults<string> = {
-          items: ['a', 'b', 'c'],
-          defaultValue: ['a'],
-          isItemDisabled: () => false,
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          itemComparer: (a, b) => a === b,
-          itemStringifier: (item) => item,
-          onChange: handleChange,
-          onHighlightChange: handleHighlightChange,
-          orientation: 'vertical',
-          selectionLimit: null,
-        };
-
-        const propsRef = React.useRef(props);
-        const [, dispatch] = useControllableReducer(reducer, undefined, propsRef);
-        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
-        return null;
-      }
-
-      render(<TestComponent />);
-      expect(handleHighlightChange.getCalls()[0].args[1]).to.equal('b');
-      expect(handleChange.notCalled).to.equal(true);
-    });
-  });
-});
diff --git a/packages/mui-base/src/useList/useControllableReducer.ts b/packages/mui-base/src/useList/useControllableReducer.ts
deleted file mode 100644
index e74d8613728700..00000000000000
--- a/packages/mui-base/src/useList/useControllableReducer.ts
+++ /dev/null
@@ -1,156 +0,0 @@
-import * as React from 'react';
-import {
-  ListReducer,
-  ListReducerAction,
-  ListState,
-  UseListParametersWithDefaults,
-} from './useList.types';
-import areArraysEqual from '../utils/areArraysEqual';
-import { ActionTypes, ListAction } from './actions.types';
-
-/**
- * Gets the current state. If the selectedValue is controlled,
- * the `value` prop is the source of truth instead of the internal state.
- */
-function getControlledState<TOption>(
-  internalState: ListState<TOption>,
-  props: UseListParametersWithDefaults<TOption>,
-) {
-  if (props.value !== undefined) {
-    return { ...internalState, selectedValues: props.value };
-  }
-
-  return internalState;
-}
-
-function areOptionsEqual<TOption>(
-  option1: TOption | null,
-  option2: TOption | null,
-  optionComparer: (optionA: TOption, optionB: TOption) => boolean,
-) {
-  if (option1 === option2) {
-    return true;
-  }
-
-  if (option1 === null || option2 === null) {
-    return false;
-  }
-
-  return optionComparer(option1, option2);
-}
-
-/**
- * Triggers change event handlers (onChange and onHighlightChange) when reducer returns changed state.
- *
- * @param nextState The next state returned by the reducer.
- * @param internalPreviousState The previous state. If the component is controlled, this is merged with the props to determine the final state.
- * @param propsRef The props with defaults applied.
- * @param lastActionRef The last action that was dispatched.
- */
-function useStateChangeDetection<TOption>(
-  nextState: ListState<TOption>,
-  internalPreviousState: ListState<TOption>,
-  propsRef: React.RefObject<UseListParametersWithDefaults<TOption>>,
-  lastActionRef: React.MutableRefObject<ListAction<TOption> | null>,
-) {
-  React.useEffect(() => {
-    if (!propsRef.current || lastActionRef.current === null) {
-      // Detect changes only if an action has been dispatched.
-      return;
-    }
-
-    if (
-      lastActionRef.current.type === ActionTypes.setValue ||
-      lastActionRef.current.type === ActionTypes.setHighlight
-    ) {
-      // Don't fire change events when the value has been changed externally (e.g. by changing the controlled prop).
-      return;
-    }
-
-    const previousState = getControlledState(internalPreviousState, propsRef.current);
-    const { itemComparer, onChange } = propsRef.current;
-
-    const previousSelectedValues = previousState?.selectedValues ?? [];
-    const nextSelectedValues = nextState.selectedValues as TOption[];
-
-    if (!areArraysEqual(nextSelectedValues, previousSelectedValues, itemComparer)) {
-      onChange?.(lastActionRef.current.event, nextSelectedValues, lastActionRef.current.type);
-    }
-
-    // Fires the highlightChange event when reducer returns changed `highlightedValue`.
-    if (
-      !areOptionsEqual(
-        internalPreviousState.highlightedValue,
-        nextState.highlightedValue,
-        propsRef.current.itemComparer,
-      )
-    ) {
-      propsRef.current?.onHighlightChange?.(
-        lastActionRef.current.event,
-        nextState.highlightedValue,
-        lastActionRef.current.type,
-      );
-    }
-
-    lastActionRef.current = null;
-  }, [
-    nextState.selectedValues,
-    nextState.highlightedValue,
-    internalPreviousState,
-    propsRef,
-    lastActionRef,
-  ]);
-}
-
-/**
- * @ignore - do not document.
- */
-export default function useControllableReducer<TOption>(
-  internalReducer: ListReducer<TOption>,
-  externalReducer: ListReducer<TOption> | undefined,
-  props: React.RefObject<UseListParametersWithDefaults<TOption>>,
-): [ListState<TOption>, (action: ListAction<TOption>) => void] {
-  const { value, defaultValue } = props.current!;
-
-  const actionRef = React.useRef<ListAction<TOption> | null>(null);
-
-  const initialSelectedValues = (value === undefined ? defaultValue : value) ?? [];
-
-  const initialState = {
-    highlightedValue: null,
-    selectedValues: initialSelectedValues,
-  };
-
-  const combinedReducer = React.useCallback(
-    (state: ListState<TOption>, action: ListReducerAction<TOption>) => {
-      actionRef.current = action;
-
-      if (externalReducer) {
-        return externalReducer(getControlledState(state, action.props), action);
-      }
-
-      return internalReducer(getControlledState(state, action.props), action);
-    },
-    [externalReducer, internalReducer],
-  );
-
-  const [nextState, dispatch] = React.useReducer(combinedReducer, initialState);
-
-  const dispatchWithProps = React.useCallback(
-    (action: ListAction<TOption>) => {
-      dispatch({
-        props: props.current,
-        ...action,
-      } as ListReducerAction<TOption>);
-    },
-    [dispatch, props],
-  );
-
-  const previousState = React.useRef<ListState<TOption>>(initialState);
-  React.useEffect(() => {
-    previousState.current = nextState;
-  }, [previousState, nextState]);
-
-  useStateChangeDetection<TOption>(nextState, previousState.current, props, actionRef);
-  return [getControlledState(nextState, props.current!), dispatchWithProps];
-}
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 4d00e62dbc8e0b..16ca8d23005720 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -5,23 +5,37 @@ import {
   UseListParametersWithDefaults,
   ListItemState,
   UseListRootSlotProps,
+  ListState,
+  ListActionAddOn,
 } from './useList.types';
 import defaultReducer from './defaultListboxReducer';
-import useControllableReducer from './useControllableReducer';
+import useControllableReducer from '../utils/useControllableReducer';
 import areArraysEqual from '../utils/areArraysEqual';
 import { EventHandlers } from '../utils/types';
 import useLatest from '../utils/useLatest';
 import useTextNavigation from '../utils/useTextNavigation';
 import useListChangeNotifiers from './useListChangeNotifiers';
 import { ActionTypes, ListAction } from './actions.types';
+import {
+  ControllableReducerAction,
+  StateChangeCallback,
+  StateComparers,
+} from '../utils/useControllableReducer.types';
+
+const noop = () => {};
+const emptyObject = {};
 
-const defaultItemComparer = <ItemValue>(item1: ItemValue, item2: ItemValue) => item1 === item2;
+const defaultItemComparer = <TOption>(optionA: TOption, optionB: TOption) => optionA === optionB;
 const defaultIsItemDisabled = () => false;
 const defaultItemStringifier = <ItemValue>(item: ItemValue) =>
   typeof item === 'string' ? item : String(item);
+const defaultGetInitialState = () => ({
+  highlightedValue: null,
+  selectedValues: [],
+});
 
-export interface ListContextValue<ItemValue> {
-  dispatch: (action: ListAction<ItemValue>) => void;
+export interface ListContextValue<ItemValue, State extends ListState<ItemValue>> {
+  dispatch: (action: ListAction<ItemValue, State>) => void;
   getItemState: (item: ItemValue) => ListItemState;
   registerHighlightChangeHandler: (handler: (item: ItemValue | null) => void) => () => void;
   registerSelectionChangeHandler: (
@@ -29,7 +43,7 @@ export interface ListContextValue<ItemValue> {
   ) => () => void;
 }
 
-export const ListContext = React.createContext<ListContextValue<any> | null>(null);
+export const ListContext = React.createContext<ListContextValue<any, any> | null>(null);
 if (process.env.NODE_ENV !== 'production') {
   ListContext.displayName = 'ListContext';
 }
@@ -42,23 +56,30 @@ if (process.env.NODE_ENV !== 'production') {
  *
  * @ignore - internal hook.
  */
-export default function useList<ItemValue>(params: UseListParameters<ItemValue>) {
+function useList<
+  ItemValue,
+  State extends ListState<ItemValue> = ListState<ItemValue>,
+  CustomAction extends ControllableReducerAction = never,
+>(params: UseListParameters<ItemValue, State, CustomAction>) {
   const {
+    controlledState: controlledProps = emptyObject,
     disabledItemsFocusable = false,
     disableListWrap = false,
     focusManagement = 'activeDescendant',
+    getInitialState = defaultGetInitialState,
     getItemDomElement,
     getItemId,
     isItemDisabled = defaultIsItemDisabled,
     listRef: externalListRef,
-    onHighlightChange,
-    itemComparer = defaultItemComparer,
+    onStateChange = noop,
     items,
+    itemComparer = defaultItemComparer,
     itemStringifier = defaultItemStringifier,
+    onChange,
+    onHighlightChange,
     orientation = 'vertical',
     selectionLimit = null,
     stateReducer: externalReducer,
-    value: valueParam,
   } = params;
 
   if (process.env.NODE_ENV !== 'production') {
@@ -82,7 +103,7 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     (
       event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
       value: ItemValue | null,
-      reason: ActionTypes,
+      reason: string,
     ) => {
       onHighlightChange?.(event, value, reason);
 
@@ -99,28 +120,84 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     [getItemDomElement, onHighlightChange, focusManagement],
   );
 
+  const stateComparers = React.useMemo(
+    () =>
+      ({
+        highlightedValue: itemComparer,
+        selectedValues: (valuesArray1, valuesArray2) =>
+          areArraysEqual(valuesArray1, valuesArray2, itemComparer),
+      } as StateComparers<State>),
+    [itemComparer],
+  );
+
+  const handleStateChange: StateChangeCallback<State> = React.useCallback(
+    (event, field, value, reason, state) => {
+      onStateChange?.(event, field, value, reason, state);
+
+      switch (field) {
+        case 'highlightedValue':
+          handleHighlightChange(
+            event as React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
+            value as ItemValue | null,
+            reason,
+          );
+          break;
+        case 'selectedValues':
+          onChange?.(
+            event as React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
+            value as ItemValue[],
+            reason,
+          );
+          break;
+        default:
+          break;
+      }
+    },
+    [handleHighlightChange, onChange, onStateChange],
+  );
+
   const propsWithDefaults: React.RefObject<UseListParametersWithDefaults<ItemValue>> = useLatest(
     {
-      ...params,
       disabledItemsFocusable,
       disableListWrap,
       focusManagement,
       isItemDisabled,
-      onHighlightChange: handleHighlightChange,
       itemComparer,
+      items,
       itemStringifier,
+      onHighlightChange: handleHighlightChange,
       orientation,
       selectionLimit,
+      stateComparers,
     },
     [params],
   );
 
-  const [{ highlightedValue, selectedValues }, dispatch] = useControllableReducer(
-    defaultReducer,
-    externalReducer,
-    propsWithDefaults,
+  const initialState = getInitialState();
+  const reducer = externalReducer ?? defaultReducer;
+
+  const actionAddOn: ListActionAddOn<ItemValue> = React.useMemo(
+    () => ({ props: propsWithDefaults }),
+    [propsWithDefaults],
   );
 
+  type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue, State>;
+
+  const [state, dispatch] = useControllableReducer<
+    State,
+    ListActionsWithCustomActions,
+    ListActionAddOn<ItemValue>
+  >({
+    reducer: reducer as any,
+    actionAddOn,
+    initialState: initialState as State,
+    controlledProps,
+    stateComparers,
+    onStateChange: handleStateChange,
+  });
+
+  const { highlightedValue, selectedValues } = state;
+
   const handleTextNavigation = useTextNavigation((searchString, event) =>
     dispatch({
       type: ActionTypes.textNavigation,
@@ -129,17 +206,6 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     }),
   );
 
-  React.useEffect(() => {
-    // if a controlled value changes, we need to update the state to keep things in sync
-    if (valueParam !== undefined && valueParam !== selectedValues) {
-      dispatch({
-        type: ActionTypes.setValue,
-        event: null,
-        values: valueParam,
-      });
-    }
-  }, [valueParam, selectedValues, dispatch]);
-
   const highlightedIndex = React.useMemo(() => {
     return highlightedValue == null
       ? -1
@@ -184,9 +250,9 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
   const setSelectedValue = React.useCallback(
     (values: ItemValue[]) => {
       dispatch({
-        type: ActionTypes.setValue,
+        type: ActionTypes.setState,
         event: null,
-        values,
+        value: { selectedValues: values } as Partial<State>,
       });
     },
     [dispatch],
@@ -195,9 +261,9 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
   const setHighlightedValue = React.useCallback(
     (item: ItemValue | null) => {
       dispatch({
-        type: ActionTypes.setHighlight,
+        type: ActionTypes.setState,
         event: null,
-        value: item,
+        value: { highlightedValue: item } as Partial<State>,
       });
     },
     [dispatch],
@@ -348,7 +414,7 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
     ],
   );
 
-  const contextValue: ListContextValue<ItemValue> = React.useMemo(
+  const contextValue: ListContextValue<ItemValue, State> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
@@ -365,10 +431,14 @@ export default function useList<ItemValue>(params: UseListParameters<ItemValue>)
 
   return {
     contextValue,
+    dispatch,
     getRootProps,
     highlightedOption: highlightedValue,
     selectedOptions: selectedValues,
     setHighlightedValue,
     setSelectedValue,
+    state,
   };
 }
+
+export default useList;
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 9c438108aa8c3a..52c62dca2a1ec1 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -1,25 +1,37 @@
 import * as React from 'react';
-import { ActionTypes, ListAction } from './actions.types';
+import { Simplify } from '@mui/types';
+import { ListAction } from './actions.types';
+import {
+  ControllableReducerAction,
+  StateChangeCallback,
+} from '../utils/useControllableReducer.types';
 
-type UseListStrictParametersRequiredKeys =
-  | 'isItemDisabled'
-  | 'disableListWrap'
+type UseListParametersWithDefaultsRequiredKeys =
   | 'disabledItemsFocusable'
+  | 'disableListWrap'
+  | 'focusManagement'
+  | 'isItemDisabled'
   | 'itemComparer'
-  | 'orientation'
+  | 'items'
   | 'itemStringifier'
+  | 'orientation'
   | 'selectionLimit';
 
-export type UseListParametersWithDefaults<ItemValue> = Omit<
-  UseListParameters<ItemValue>,
-  UseListStrictParametersRequiredKeys
-> &
-  Required<Pick<UseListParameters<ItemValue>, UseListStrictParametersRequiredKeys>>;
+export type UseListParametersWithDefaults<ItemValue> = Simplify<
+  Required<Pick<UseListParameters<ItemValue, any, any>, UseListParametersWithDefaultsRequiredKeys>>
+>;
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
 
-export type ListReducerAction<T> = ListAction<T> & {
-  props: UseListParametersWithDefaults<T>;
+export type ListReducerAction<ItemValue, State extends ListState<ItemValue>> = ListAction<
+  ItemValue,
+  State
+> & {
+  props: React.RefObject<UseListParametersWithDefaults<ItemValue>>;
+};
+
+export type ListActionAddOn<ItemValue> = {
+  props: React.RefObject<UseListParametersWithDefaults<ItemValue>>;
 };
 
 export interface ListState<ItemValue> {
@@ -27,16 +39,17 @@ export interface ListState<ItemValue> {
   selectedValues: ItemValue[];
 }
 
-export type ListReducer<ItemValue> = (
-  state: ListState<ItemValue>,
-  action: ListReducerAction<ItemValue>,
-) => ListState<ItemValue>;
+export type ListReducer<ItemValue, State extends ListState<ItemValue>> = (
+  state: State,
+  action: ListReducerAction<ItemValue, State>,
+) => State;
 
-export interface UseListParameters<ItemValue> {
-  /**
-   * The default selected value. Use when the list component is not controlled.
-   */
-  defaultValue?: ItemValue[];
+export interface UseListParameters<
+  ItemValue,
+  State extends ListState<ItemValue> = ListState<ItemValue>,
+  CustomAction extends ControllableReducerAction = never,
+> {
+  controlledState?: Partial<State>;
   /**
    * If `true`, it will be possible to highlight disabled items.
    * @default false
@@ -62,6 +75,7 @@ export interface UseListParameters<ItemValue> {
    * @param itemValue List item to get the id for.
    */
   getItemId?: (itemValue: ItemValue) => string | undefined;
+  getInitialState?: () => State;
   /**
    * A function that determines if a particular item is disabled.
    * @default () => false
@@ -72,22 +86,29 @@ export interface UseListParameters<ItemValue> {
    */
   listRef?: React.Ref<any>;
   /**
-   * Callback fired when the selected value changes.
+   * Callback fired when the value changes.
    */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    values: ItemValue[],
-    reason: ActionTypes,
+    value: ItemValue[],
+    reason: string,
   ) => void;
   /**
-   * Callback fired when the highlighted item changes.
-   * The `value` is null if there is no highlighted item.
+   * Callback fired when the highlighted option changes.
    */
   onHighlightChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    value: ItemValue | null,
-    reason: ActionTypes,
+    option: ItemValue | null,
+    reason: string,
   ) => void;
+  /**
+   * Callback fired when the selected value changes.
+   */
+  onStateChange?: StateChangeCallback<State>;
+  /**
+   * Callback fired when the highlighted item changes.
+   * The `value` is null if there is no highlighted item.
+   */
   /**
    * A function that tests equality between two items' values.
    * @default (a, b) => a === b
@@ -122,11 +143,10 @@ export interface UseListParameters<ItemValue> {
    * Custom state reducer function. It calculates the new state (highlighted and selected items)
    * based on the previous one and the performed action.
    */
-  stateReducer?: ListReducer<ItemValue>;
-  /**
-   * The selected value. Use when the list component is controlled.
-   */
-  value?: ItemValue[];
+  stateReducer?: (
+    state: State,
+    action: (ListAction<ItemValue, State> | CustomAction) & ListActionAddOn<ItemValue>,
+  ) => State;
 }
 
 export interface ListItemState {
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
index 509dccbac956a2..d7e2c4d97c5b2c 100644
--- a/packages/mui-base/src/useMenu/MenuProvider.tsx
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -2,9 +2,10 @@ import * as React from 'react';
 import { MenuItemMetadata } from '../useMenuItem';
 import { ListContext, ListContextValue } from '../useList';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+import type { MenuInternalState } from './useMenu.types';
 
 export type MenuProviderValue = CompoundComponentContextValue<string, MenuItemMetadata> &
-  ListContextValue<string>;
+  ListContextValue<string, MenuInternalState>;
 
 export interface MenuProviderProps {
   value: MenuProviderValue;
@@ -25,7 +26,7 @@ export default function MenuProvider(props: MenuProviderProps) {
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<string> = React.useMemo(
+  const listContextValue: ListContextValue<string, MenuInternalState> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 69b5919a0ce49d..d9b75bcc449305 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -2,42 +2,21 @@ import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import useList, {
   defaultListboxReducer,
-  ListState,
   ActionTypes,
-  ListReducerAction,
+  ListActionAddOn,
+  ListAction,
 } from '../useList';
-import { UseMenuListboxSlotProps, UseMenuParameters, UseMenuReturnValue } from './useMenu.types';
+import {
+  MenuInternalState,
+  UseMenuListboxSlotProps,
+  UseMenuParameters,
+  UseMenuReturnValue,
+} from './useMenu.types';
 import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { MenuItemMetadata } from '../useMenuItem';
+import { StateChangeCallback } from '../utils/useControllableReducer.types';
 
-function stateReducer(
-  state: ListState<string>,
-  action: ListReducerAction<string>,
-): ListState<string> {
-  if (
-    action.type === ActionTypes.blur ||
-    action.type === ActionTypes.itemHover ||
-    action.type === ActionTypes.setValue
-  ) {
-    return state;
-  }
-
-  const newState = defaultListboxReducer(state, action);
-
-  if (
-    action.type !== ActionTypes.setHighlight &&
-    newState.highlightedValue === null &&
-    action.props.items.length > 0
-  ) {
-    return {
-      ...newState,
-      highlightedValue: action.props.items[0],
-    };
-  }
-
-  return newState;
-}
 /**
  *
  * Demos:
@@ -49,7 +28,7 @@ function stateReducer(
  * - [useMenu API](https://mui.com/base/react-menu/hooks-api/#use-menu)
  */
 export default function useMenu(parameters: UseMenuParameters = {}): UseMenuReturnValue {
-  const { listboxRef: listboxRefProp, open = false, onClose, listboxId } = parameters;
+  const { defaultOpen, listboxRef: listboxRefProp, open: openProp, onOpenChange } = parameters;
 
   const listboxRef = React.useRef<HTMLElement | null>(null);
   const handleRef = useForkRef(listboxRef, listboxRefProp);
@@ -72,63 +51,93 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     [subitems],
   );
 
+  const stateReducer = React.useCallback(
+    (
+      state: MenuInternalState,
+      action: ListAction<string, MenuInternalState> & ListActionAddOn<string>,
+    ): MenuInternalState => {
+      if (action.type === ActionTypes.itemHover || action.type === ActionTypes.setState) {
+        return state;
+      }
+
+      const newState = defaultListboxReducer(state, action);
+
+      // make sure an item is always highlighted
+      if (newState.highlightedValue === null && action.props.current!.items.length > 0) {
+        return {
+          ...newState,
+          highlightedValue: action.props.current!.items[0],
+        };
+      }
+
+      if (action.type === ActionTypes.keyDown) {
+        if (action.event.key === 'Escape') {
+          return {
+            ...newState,
+            open: false,
+          };
+        }
+      }
+
+      if (action.type === ActionTypes.blur) {
+        if (!listboxRef.current?.contains(action.event.relatedTarget)) {
+          return {
+            ...newState,
+            open: false,
+          };
+        }
+      }
+
+      return newState;
+    },
+    [],
+  );
+
+  const controlledState = React.useMemo(() => ({ open: openProp }), [openProp]);
+
+  const stateChangeHandler: StateChangeCallback<MenuInternalState> = React.useCallback(
+    (event, field, fieldValue, reason, state) => {
+      if (field === 'open') {
+        onOpenChange?.(fieldValue as boolean);
+
+        if (state.highlightedValue !== null) {
+          subitems.get(state.highlightedValue)?.ref.current?.focus();
+        }
+      }
+    },
+    [onOpenChange, subitems],
+  );
+
   const {
     getRootProps,
     highlightedOption,
-    setHighlightedValue: setListboxHighlight,
     contextValue: listContextValue,
-  } = useList({
+    state: { open },
+  } = useList<string, MenuInternalState>({
+    controlledState,
     disabledItemsFocusable: true,
     focusManagement: 'DOM',
     getItemDomElement,
-    id: listboxId,
+    getInitialState: () => ({
+      selectedValues: [],
+      highlightedValue: null,
+      open: defaultOpen ?? false,
+    }),
     isItemDisabled: (id) => subitems?.get(id)?.disabled || false,
     items: subitemKeys,
     itemStringifier: (id: string) =>
       subitems.get(id)?.label || subitems.get(id)?.ref.current?.innerText,
     listRef: handleRef,
+    onStateChange: stateChangeHandler,
     selectionLimit: 0,
     stateReducer,
   });
 
-  const highlightFirstItem = React.useCallback(() => {
-    if (subitems.size > 0) {
-      setListboxHighlight(subitems.get(Array.from(subitems.keys())[0])!.id);
-    }
-  }, [subitems, setListboxHighlight]);
-
-  const highlightLastItem = React.useCallback(() => {
-    if (subitems.size > 0) {
-      setListboxHighlight(subitems.get(Array.from(subitems.keys())[subitems.size - 1])!.id);
-    }
-  }, [subitems, setListboxHighlight]);
-
   React.useEffect(() => {
-    if (open) {
-      // TODO: ignore disabled items
-      highlightFirstItem();
+    if (open && highlightedOption === subitemKeys[0]) {
       subitems.get(subitemKeys[0])?.ref?.current?.focus();
     }
-  }, [open, highlightFirstItem, subitems, subitemKeys]);
-
-  const createHandleKeyDown = (otherHandlers: EventHandlers) => (e: React.KeyboardEvent) => {
-    otherHandlers.onKeyDown?.(e);
-    if (e.defaultPrevented) {
-      return;
-    }
-
-    if (e.key === 'Escape' && open) {
-      onClose?.();
-    }
-  };
-
-  const createHandleBlur = (otherHandlers: EventHandlers) => (e: React.FocusEvent) => {
-    otherHandlers.onBlur?.(e);
-
-    if (!listboxRef.current?.contains(e.relatedTarget)) {
-      onClose?.();
-    }
-  };
+  }, [open, highlightedOption, subitems, subitemKeys]);
 
   React.useEffect(() => {
     // set focus to the highlighted item (but prevent stealing focus from other elements on the page)
@@ -140,11 +149,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
   const getListboxProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
   ): UseMenuListboxSlotProps => {
-    const rootProps = getRootProps({
-      ...otherHandlers,
-      onBlur: createHandleBlur(otherHandlers),
-      onKeyDown: createHandleKeyDown(otherHandlers),
-    });
+    const rootProps = getRootProps(otherHandlers);
     return {
       ...otherHandlers,
       ...rootProps,
@@ -161,8 +166,10 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     },
     getListboxProps,
     highlightedOption,
-    highlightFirstItem,
-    highlightLastItem,
+    // TODO: remove
+    highlightFirstItem: () => {},
+    highlightLastItem: () => {},
     menuItems: subitems,
+    open,
   };
 }
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 0d0909831ecf7e..72902022b0a3e3 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -1,12 +1,13 @@
 import * as React from 'react';
-import { UseListRootSlotProps } from '../useList';
+import { ListState, UseListRootSlotProps } from '../useList';
 import { MenuItemMetadata } from '../useMenuItem';
 import { EventHandlers } from '../utils/types';
 import { MenuProviderValue } from './MenuProvider';
 
 export interface UseMenuParameters {
+  defaultOpen?: boolean;
   open?: boolean;
-  onClose?: () => void;
+  onOpenChange?: (open: boolean) => void;
   listboxId?: string;
   listboxRef?: React.Ref<any>;
 }
@@ -40,6 +41,7 @@ export interface UseMenuReturnValue {
    * Items in the menu listbox.
    */
   menuItems: Map<string, MenuItemMetadata>;
+  open: boolean;
 }
 
 interface UseMenuListboxSlotEventHandlers {
@@ -53,3 +55,7 @@ export type UseMenuListboxSlotProps<TOther = {}> = UseListRootSlotProps<
   ref: React.Ref<any>;
   role: React.AriaRole;
 };
+
+export interface MenuInternalState extends ListState<string> {
+  open: boolean;
+}
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
index 9288def502bdd0..1f162e9383879b 100644
--- a/packages/mui-base/src/useSelect/SelectProvider.tsx
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -2,9 +2,10 @@ import * as React from 'react';
 import { ListContext, ListContextValue } from '../useList';
 import { SelectOption } from '../useOption/useOption.types';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
+import type { SelectInternalState } from './useSelect.types';
 
 export type SelectProviderValue<Value> = CompoundComponentContextValue<Value, SelectOption<Value>> &
-  ListContextValue<Value>;
+  ListContextValue<Value, SelectInternalState<Value>>;
 
 export interface SelectProviderProps<Value> {
   value: SelectProviderValue<Value>;
@@ -25,7 +26,7 @@ export default function SelectProvider<Value>(props: SelectProviderProps<Value>)
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<Value> = React.useMemo(
+  const listContextValue: ListContextValue<Value, SelectInternalState<Value>> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index f8dce8821c0ef7..19b5bdef942b05 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -6,6 +6,10 @@ import {
 } from '@mui/utils';
 import useButton from '../useButton';
 import {
+  ButtonClickAction,
+  SelectAction,
+  SelectActionTypes,
+  SelectInternalState,
   SelectValue,
   UseSelectButtonSlotProps,
   UseSelectListboxSlotProps,
@@ -13,11 +17,11 @@ import {
   UseSelectResult,
 } from './useSelect.types';
 import useList, {
-  ListReducer,
   defaultListboxReducer,
   ActionTypes,
   UseListParameters,
-  ListState,
+  ListAction,
+  ListActionAddOn,
 } from '../useList';
 import { EventHandlers } from '../utils/types';
 import defaultOptionStringifier from '../SelectUnstyled/defaultOptionStringifier';
@@ -48,7 +52,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
     onChange,
     onHighlightChange,
     onOpenChange,
-    open = false,
+    open: openProp,
     options: optionsParam,
     optionStringifier = defaultOptionStringifier,
     value: valueProp,
@@ -118,77 +122,47 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
   const handleListboxRef = useForkRef(listboxRefProp, listboxRef, focusListboxIfRequested);
 
-  React.useEffect(() => {
-    focusListboxIfRequested();
-  }, [focusListboxIfRequested]);
-
-  React.useEffect(() => {
-    requestListboxFocus(open);
-  }, [open]);
-
-  const createHandleMouseDown =
-    (otherHandlers?: Record<string, React.EventHandler<any>>) =>
-    (event: React.MouseEvent<HTMLElement>) => {
-      otherHandlers?.onMouseDown?.(event);
-      if (!event.defaultPrevented && open) {
-        ignoreClick.current = true;
-      }
-    };
-
-  const createHandleButtonClick =
-    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.MouseEvent) => {
-      otherHandlers?.onClick?.(event);
-      if (!event.defaultPrevented && !ignoreClick.current) {
-        onOpenChange?.(!open);
-      }
-
-      ignoreClick.current = false;
-    };
-
-  const createHandleButtonKeyDown =
-    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.KeyboardEvent) => {
-      otherHandlers?.onKeyDown?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
-
-      if (event.key === 'Enter') {
-        ignoreEnterKeyUp.current = true;
-      }
+  const stateReducer = React.useCallback(
+    (
+      state: SelectInternalState<TValue>,
+      action: (ListAction<TValue, SelectInternalState<TValue>> | SelectAction) &
+        ListActionAddOn<TValue>,
+    ) => {
+      const { open } = state;
 
-      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-        event.preventDefault();
-        onOpenChange?.(true);
-      }
-    };
-
-  const createHandleListboxKeyUp =
-    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.KeyboardEvent) => {
-      otherHandlers?.onKeyUp?.(event);
-      if (event.defaultPrevented) {
-        return;
-      }
+      switch (action.type) {
+        case SelectActionTypes.buttonClick:
+          return {
+            ...state,
+            open: !open,
+          };
 
-      const closingKeys = multiple ? ['Escape'] : ['Escape', 'Enter', ' '];
+        case SelectActionTypes.buttonArrowKeyDown:
+          if (action.event.key === 'ArrowDown') {
+            return {
+              ...state,
+              open: true,
+            };
+          }
 
-      if (open && !ignoreEnterKeyUp.current && closingKeys.includes(event.key)) {
-        buttonRef?.current?.focus();
-      }
+          if (action.event.key === 'ArrowUp') {
+            return {
+              ...state,
+              open: true,
+              // TODO: highlight last item
+            };
+          }
 
-      ignoreEnterKeyUp.current = false;
-    };
+          break;
 
-  const createHandleListboxBlur =
-    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.FocusEvent) => {
-      otherHandlers?.onBlur?.(event);
-      if (!event.defaultPrevented) {
-        onOpenChange?.(false);
+        default:
+          break;
       }
-    };
 
-  const listboxReducer: ListReducer<TValue> = React.useCallback(
-    (state, action) => {
-      const newState: ListState<TValue> = defaultListboxReducer<TValue>(state, action);
+      const newState: SelectInternalState<TValue> = defaultListboxReducer(
+        state,
+        action as ListAction<TValue, SelectInternalState<TValue>> & ListActionAddOn<TValue>,
+      );
 
       switch (action.type) {
         case ActionTypes.keyDown:
@@ -204,10 +178,31 @@ function useSelect<TValue, Multiple extends boolean = false>(
             };
           }
 
+          if (
+            !multiple &&
+            (action.event.key === 'Enter' ||
+              action.event.key === ' ' ||
+              action.event.key === 'Escape')
+          ) {
+            return {
+              ...newState,
+              open: false,
+            };
+          }
+
           break;
 
-        case ActionTypes.blur:
-        case ActionTypes.setValue:
+        case ActionTypes.itemClick:
+          if (!multiple) {
+            return {
+              ...newState,
+              open: false,
+            };
+          }
+
+          break;
+
+        case ActionTypes.setState:
         case ActionTypes.itemsChange:
           return {
             ...newState,
@@ -215,13 +210,21 @@ function useSelect<TValue, Multiple extends boolean = false>(
               newState.selectedValues.length > 0 ? newState.selectedValues[0] : null,
           };
 
+        case ActionTypes.blur:
+          return {
+            ...newState,
+            highlightedValue:
+              newState.selectedValues.length > 0 ? newState.selectedValues[0] : null,
+            open: false,
+          };
+
         default:
           return newState;
       }
 
       return newState;
     },
-    [open, multiple],
+    [multiple],
   );
 
   const {
@@ -255,9 +258,26 @@ function useSelect<TValue, Multiple extends boolean = false>(
     [options, optionStringifier],
   );
 
-  const useListboxParameters: UseListParameters<TValue> = {
-    defaultValue,
+  const controlledState = React.useMemo(
+    () => ({
+      selectedValues: value,
+      open: openProp,
+    }),
+    [value, openProp],
+  );
+
+  const useListboxParameters: UseListParameters<
+    TValue,
+    SelectInternalState<TValue>,
+    SelectAction
+  > = {
+    getInitialState: () => ({
+      highlightedValue: null,
+      selectedValues: defaultValue ?? [],
+      open: false,
+    }),
     getItemId: (itemValue) => options.get(itemValue)?.id,
+    controlledState,
     isItemDisabled,
     listRef: handleListboxRef,
     onChange: (e, newValues) => {
@@ -270,28 +290,95 @@ function useSelect<TValue, Multiple extends boolean = false>(
     onHighlightChange: (e, newValue) => {
       onHighlightChange?.(e, newValue ?? null);
     },
+    onStateChange: (e, field, fieldValue) => {
+      if (field === 'open') {
+        onOpenChange?.(fieldValue as boolean);
+        if (fieldValue === false && e?.type !== 'blur') {
+          buttonRef.current?.focus();
+        }
+      }
+    },
     items: optionValues,
     itemStringifier: stringifyOption,
     selectionLimit: multiple ? null : 1,
-    stateReducer: listboxReducer,
-    value,
+    stateReducer,
   };
 
   const {
+    dispatch,
     getRootProps: getListboxRootProps,
     highlightedOption,
     selectedOptions,
     contextValue: listContextValue,
+    state,
   } = useList(useListboxParameters);
 
-  useEnhancedEffect(() => {
-    // TODO: the listbox should close when an option is clicked (even if it's already selected)
-    // close the listbox when an option is selected
-    if (!multiple && listboxRef.current?.contains(document.activeElement)) {
-      onOpenChange?.(false);
-      buttonRef.current?.focus();
-    }
-  }, [multiple, onOpenChange, selectedOptions]);
+  const { open } = state;
+
+  React.useEffect(() => {
+    focusListboxIfRequested();
+  }, [focusListboxIfRequested]);
+
+  React.useEffect(() => {
+    requestListboxFocus(open);
+  }, [open]);
+
+  const createHandleMouseDown =
+    (otherHandlers?: Record<string, React.EventHandler<any>>) =>
+    (event: React.MouseEvent<HTMLElement>) => {
+      otherHandlers?.onMouseDown?.(event);
+      if (!event.defaultPrevented && open) {
+        ignoreClick.current = true;
+      }
+    };
+
+  const createHandleButtonClick =
+    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.MouseEvent) => {
+      otherHandlers?.onClick?.(event);
+      if (!event.defaultPrevented && !ignoreClick.current) {
+        const action: ButtonClickAction = {
+          type: SelectActionTypes.buttonClick,
+          event,
+        };
+
+        dispatch(action);
+      }
+
+      ignoreClick.current = false;
+    };
+
+  const createHandleButtonKeyDown =
+    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.KeyboardEvent) => {
+      otherHandlers?.onKeyDown?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      if (event.key === 'Enter') {
+        ignoreEnterKeyUp.current = true;
+      }
+
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+        event.preventDefault();
+        dispatch({ type: SelectActionTypes.buttonArrowKeyDown, event });
+      }
+    };
+
+  const createHandleListboxKeyUp =
+    (otherHandlers?: Record<string, React.EventHandler<any>>) => (event: React.KeyboardEvent) => {
+      otherHandlers?.onKeyUp?.(event);
+      if (event.defaultPrevented) {
+        return;
+      }
+
+      const closingKeys = multiple ? ['Escape'] : ['Escape', 'Enter', ' '];
+
+      if (open && !ignoreEnterKeyUp.current && closingKeys.includes(event.key)) {
+        buttonRef?.current?.focus();
+      }
+
+      ignoreEnterKeyUp.current = false;
+    };
 
   useEnhancedEffect(() => {
     // Scroll to the currently highlighted option.
@@ -340,7 +427,6 @@ function useSelect<TValue, Multiple extends boolean = false>(
     return {
       ...getListboxRootProps({
         ...otherHandlers,
-        onBlur: createHandleListboxBlur(otherHandlers),
         onKeyUp: createHandleListboxKeyUp(otherHandlers),
       }),
       id: listboxId,
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index b1acddc153e675..53ddee3ff81f5c 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { UseButtonRootSlotProps } from '../useButton';
-import { UseListRootSlotProps } from '../useList';
+import { ListState, UseListRootSlotProps } from '../useList';
 import { SelectOption } from '../useOption/useOption.types';
 import { EventHandlers } from '../utils/types';
 import { SelectProviderValue } from './SelectProvider';
@@ -84,3 +84,27 @@ export interface UseSelectResult<TValue, Multiple> {
   options: TValue[];
   value: SelectValue<TValue, Multiple>;
 }
+
+const ACTION_TYPES_BUTTON_CLICK = 'buttonClick';
+const ACTION_TYPES_BUTTON_ARROW_KEY_DOWN = 'buttonArrowKeyDown';
+
+export const SelectActionTypes = {
+  buttonClick: ACTION_TYPES_BUTTON_CLICK,
+  buttonArrowKeyDown: ACTION_TYPES_BUTTON_ARROW_KEY_DOWN,
+} as const;
+
+export interface ButtonClickAction {
+  type: typeof ACTION_TYPES_BUTTON_CLICK;
+  event: React.MouseEvent;
+}
+
+export interface ButtonArrowKeyDownAction {
+  type: typeof ACTION_TYPES_BUTTON_ARROW_KEY_DOWN;
+  event: React.KeyboardEvent;
+}
+
+export type SelectAction = ButtonClickAction | ButtonArrowKeyDownAction;
+
+export interface SelectInternalState<TValue> extends ListState<TValue> {
+  open: boolean;
+}
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index 68daabd4eba13a..245db3a65ee3e2 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -1,10 +1,10 @@
 import * as React from 'react';
-import { ListContext, ListContextValue } from '../useList';
+import { ListContext, ListContextValue, ListState } from '../useList';
 import { TabMetadata } from '../useTabs/useTabs';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 
 export type TabsListProviderValue = CompoundComponentContextValue<string | number, TabMetadata> &
-  ListContextValue<string | number>;
+  ListContextValue<string | number, ListState<string | number>>;
 
 export interface TabsListProviderProps {
   value: TabsListProviderValue;
@@ -27,7 +27,10 @@ export default function TabsListProvider(props: TabsListProviderProps) {
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<string | number> = React.useMemo(
+  const listContextValue: ListContextValue<
+    string | number,
+    ListState<string | number>
+  > = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 34391d4788eaaa..f35c8cd48c90e0 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -13,6 +13,7 @@ import useList, {
   ActionTypes,
   defaultListboxReducer,
   ListReducer,
+  ListState,
   UseListParameters,
 } from '../useList';
 
@@ -60,14 +61,14 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
 
   const isRtl = direction === 'rtl';
 
-  let listOrientation: UseListParameters<any>['orientation'];
+  let listOrientation: UseListParameters<any, any>['orientation'];
   if (orientation === 'vertical') {
     listOrientation = 'vertical';
   } else {
     listOrientation = isRtl ? 'horizontal-rtl' : 'horizontal-ltr';
   }
 
-  const stateReducer: ListReducer<string | number> = React.useCallback(
+  const stateReducer: ListReducer<string | number, ListState<string | number>> = React.useCallback(
     (state, action) => {
       const newState = defaultListboxReducer(state, action);
 
@@ -78,10 +79,10 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
         };
       }
 
-      if (action.type === ActionTypes.setValue && action.values != null) {
+      if (action.type === ActionTypes.setState && action.value.selectedValues != null) {
         return {
           ...newState,
-          highlightedValue: action.values[0],
+          highlightedValue: action.value.selectedValues[0],
         };
       }
 
@@ -97,14 +98,6 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     [selectionFollowsFocus],
   );
 
-  const listboxValue = React.useMemo(() => {
-    if (value == null) {
-      return [];
-    }
-
-    return [value];
-  }, [value]);
-
   const handleChange = React.useCallback(
     (
       event:
@@ -119,12 +112,22 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     [onSelected],
   );
 
+  const controlledState = React.useMemo(() => {
+    if (value === undefined) {
+      return {};
+    }
+
+    return value != null ? { selectedValues: [value] } : { selectedValues: [] };
+  }, [value]);
+
   const {
+    contextValue: listContextValue,
+    dispatch,
     getRootProps: getListboxRootProps,
-    selectedOptions,
     highlightedOption,
-    contextValue: listContextValue,
+    selectedOptions,
   } = useList({
+    controlledState,
     disabledItemsFocusable: !selectionFollowsFocus,
     focusManagement: 'DOM',
     getItemDomElement: getTabElement,
@@ -135,9 +138,24 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     orientation: listOrientation,
     selectionLimit: 1,
     stateReducer,
-    value: listboxValue,
   });
 
+  React.useEffect(() => {
+    if (value === undefined) {
+      return;
+    }
+
+    if (value != null) {
+      dispatch({
+        type: ActionTypes.setState,
+        event: null,
+        value: {
+          highlightedValue: value,
+        },
+      });
+    }
+  }, [dispatch, value]);
+
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabsListRootSlotProps<TOther> => {
diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
new file mode 100644
index 00000000000000..7b5fa114194559
--- /dev/null
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -0,0 +1,325 @@
+import { expect } from 'chai';
+import * as React from 'react';
+import { spy } from 'sinon';
+import { createRenderer } from 'test/utils';
+import useControllableReducer from './useControllableReducer';
+import {
+  ControllableReducerParameters,
+  SetStateAction,
+  setStateActionType,
+} from './useControllableReducer.types';
+
+interface TestState {
+  make: string;
+  model: string;
+  productionYear: number;
+  features?: string[];
+}
+
+interface UpdateProductionYearAction {
+  type: 'updateProductionYear';
+  value: number;
+  event: null;
+}
+
+interface UpdateFeaturesAction {
+  type: 'updateFeatures';
+  value: string[];
+}
+
+describe('useControllableReducer', () => {
+  const { render } = createRenderer();
+
+  describe('param: reducer', () => {
+    it('calls the provided reducer', () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const reducer = spy((state: TestState, action: SetStateAction<TestState>) => {
+        return {
+          ...state,
+          ...action.value,
+        };
+      });
+
+      const actionToDispatch: SetStateAction<TestState> = {
+        type: setStateActionType,
+        value: { make: 'BMW' },
+        event: null,
+      };
+
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        SetStateAction<TestState>
+      > = {
+        reducer,
+        controlledProps: {},
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+      };
+
+      function TestComponent() {
+        const [state, dispatch] = useControllableReducer(reducerParameters);
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return (
+          <p>
+            {state.make} {state.model} ({state.productionYear})
+          </p>
+        );
+      }
+
+      const { container } = render(<TestComponent />);
+      expect(reducer.getCalls()[0].args[1]).to.deep.equal({ ...actionToDispatch });
+      expect(container.firstChild).to.have.text('BMW 3 (2022)');
+    });
+  });
+
+  describe('param: initialProps', () => {
+    it('sets the initial state', () => {
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        SetStateAction<TestState>
+      > = {
+        reducer: (state) => state,
+        controlledProps: {},
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+      };
+
+      function TestComponent() {
+        const [state] = useControllableReducer(reducerParameters);
+        return (
+          <p>
+            {state.make} {state.model} ({state.productionYear})
+          </p>
+        );
+      }
+
+      const { container } = render(<TestComponent />);
+      expect(container.firstChild).to.have.text('Mazda 3 (2022)');
+    });
+  });
+
+  describe('param: controlledProps', () => {
+    it('overwrites the state field with the corresponding controlled prop value', () => {
+      const reducer = (state: TestState, action: SetStateAction<TestState>) => {
+        // Even though the initial state is set to 'Mazda', the controlled prop overwrites it.
+        expect(state.make).to.equal('Tesla');
+
+        return {
+          ...state,
+          ...action.value,
+        };
+      };
+
+      const actionToDispatch: SetStateAction<TestState> = {
+        type: setStateActionType,
+        value: { make: 'BMW' },
+        event: null,
+      };
+
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        SetStateAction<TestState>
+      > = {
+        reducer,
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+      };
+
+      function TestComponent(props: { make: string }) {
+        const [state, dispatch] = useControllableReducer<TestState, SetStateAction<TestState>>({
+          ...reducerParameters,
+          controlledProps: { make: props.make },
+        });
+
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return (
+          <p>
+            {state.make} {state.model} ({state.productionYear})
+          </p>
+        );
+      }
+
+      const { container, setProps } = render(<TestComponent make="Tesla" />);
+      expect(container.firstChild).to.have.text('Tesla 3 (2022)');
+
+      setProps({ make: 'Mazda' });
+      expect(container.firstChild).to.have.text('Mazda 3 (2022)');
+    });
+  });
+
+  describe('param: stateComparers', () => {
+    it('uses the provided state comparers', () => {
+      const reducer = (state: TestState, action: UpdateFeaturesAction) => {
+        return {
+          ...state,
+          features: action.value,
+        };
+      };
+
+      const actionToDispatch: UpdateFeaturesAction = {
+        type: 'updateFeatures',
+        value: ['ABS', 'Traction control'],
+      };
+
+      const onStateChangeSpy = spy();
+
+      const reducerParameters: ControllableReducerParameters<TestState, UpdateFeaturesAction> = {
+        reducer,
+        controlledProps: {},
+        initialState: {
+          make: 'Mazda',
+          model: '3',
+          productionYear: 2022,
+          features: ['ABS', 'Traction control'],
+        },
+        stateComparers: {
+          // deep comparison of the features array
+          features: (a, b) =>
+            a !== undefined &&
+            b !== undefined &&
+            a.length === b.length &&
+            a.every((v, i) => v === b[i]),
+        },
+        onStateChange: onStateChangeSpy,
+      };
+
+      function TestComponent() {
+        const [, dispatch] = useControllableReducer(reducerParameters);
+
+        // The features array is new, but it contents remain the same.
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return null;
+      }
+
+      render(<TestComponent />);
+      expect(onStateChangeSpy.callCount).to.equal(0);
+    });
+  });
+
+  describe('param: onStateChange', () => {
+    it('calls onStateChange when the reducer returns a modified selected value', () => {
+      const reducer = spy((state: TestState, action: UpdateProductionYearAction) => {
+        return {
+          ...state,
+          productionYear: action.value,
+        };
+      });
+
+      const actionToDispatch = {
+        type: 'updateProductionYear' as const,
+        event: null,
+        value: 2010,
+      };
+
+      const handleChange = spy();
+
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        UpdateProductionYearAction
+      > = {
+        reducer,
+        controlledProps: {},
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+        onStateChange: handleChange,
+      };
+
+      function TestComponent() {
+        const [, dispatch] = useControllableReducer(reducerParameters);
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return null;
+      }
+
+      render(<TestComponent />);
+      expect(handleChange.called).to.equal(true);
+      expect(handleChange.getCalls()[0].args).to.deep.equal([
+        null,
+        'productionYear',
+        2010,
+        'updateProductionYear',
+        {
+          make: 'Mazda',
+          model: '3',
+          productionYear: 2010,
+        },
+      ]);
+    });
+
+    it('does not call onStateChange when the state is updated via the SetStateAction', () => {
+      const reducer = spy((state: TestState, action: SetStateAction<TestState>) => {
+        return {
+          ...state,
+          ...action.value,
+        };
+      });
+
+      const actionToDispatch = {
+        type: 'setState' as const,
+        event: null,
+        value: { productionYear: 2010 },
+      };
+
+      const handleChange = spy();
+
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        SetStateAction<TestState>
+      > = {
+        reducer,
+        controlledProps: {},
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+        onStateChange: handleChange,
+      };
+
+      function TestComponent() {
+        const [, dispatch] = useControllableReducer(reducerParameters);
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return null;
+      }
+
+      render(<TestComponent />);
+      expect(handleChange.called).to.equal(false);
+    });
+  });
+
+  describe('param: actionAddOn', () => {
+    it('augments actions with the object provided to the reducer', () => {
+      const reducer = (
+        state: TestState,
+        action: SetStateAction<TestState> & { overrideProductionYear: number },
+      ) => {
+        return {
+          ...state,
+          ...action.value,
+          productionYear: action.overrideProductionYear,
+        };
+      };
+
+      const actionToDispatch = {
+        type: 'setState' as const,
+        event: null,
+        value: { productionYear: 2010, make: 'BMW' },
+      };
+
+      const reducerParameters: ControllableReducerParameters<
+        TestState,
+        SetStateAction<TestState>,
+        { overrideProductionYear: number }
+      > = {
+        reducer,
+        controlledProps: {},
+        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
+        actionAddOn: { overrideProductionYear: 2016 },
+      };
+
+      function TestComponent() {
+        const [state, dispatch] = useControllableReducer(reducerParameters);
+        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
+        return (
+          <p>
+            {state.make} {state.model} ({state.productionYear})
+          </p>
+        );
+      }
+
+      const { container } = render(<TestComponent />);
+      expect(container.firstChild).to.have.text('BMW 3 (2016)');
+    });
+  });
+});
diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
new file mode 100644
index 00000000000000..4ba2ae8c5ddc87
--- /dev/null
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -0,0 +1,168 @@
+import * as React from 'react';
+import {
+  ControllableReducerAction,
+  ControllableReducerParameters,
+  setStateActionType,
+  StateChangeCallback,
+  StateComparers,
+} from './useControllableReducer.types';
+
+function areEqual(a: any, b: any): boolean {
+  return a === b;
+}
+
+const EMPTY_OBJECT = {};
+const NOOP = () => {};
+
+/**
+ * Gets the current state augmented with controlled values from the outside.
+ * If a state item has a corresponding controlled value, it will be used instead of the internal state.
+ */
+function getControlledState<State>(internalState: State, controlledProps: Partial<State>) {
+  const augmentedState = { ...internalState };
+  (Object.keys(controlledProps) as (keyof State)[]).forEach((key) => {
+    if (controlledProps[key] !== undefined) {
+      (augmentedState as Record<keyof State, any>)[key] = controlledProps[key];
+    }
+  });
+
+  return augmentedState;
+}
+
+/**
+ * Triggers the change event handler when reducer returns changed state.
+ *
+ * @param nextState The next state returned by the reducer.
+ * @param internalPreviousState The previous state. If the component is controlled, this is merged with the props to determine the final state.
+ * @param stateComparers Comparers for each state item. If a state item has a corresponding comparer, it will be used to determine if the state has changed.
+ * @param onStateChange The change event handler.
+ * @param controlledProps The external props used to override the state items.
+ * @param lastActionRef The last action that was dispatched.
+ */
+function useStateChangeDetection<State extends {}>(
+  nextState: State,
+  internalPreviousState: State,
+  stateComparers: StateComparers<State>,
+  onStateChange: StateChangeCallback<State>,
+  controlledProps: Partial<State>,
+  lastActionRef: React.MutableRefObject<ControllableReducerAction | null>,
+) {
+  React.useEffect(() => {
+    if (lastActionRef.current === null) {
+      // Detect changes only if an action has been dispatched.
+      return;
+    }
+
+    if (lastActionRef.current.type === setStateActionType) {
+      // Don't fire change events when the value has been changed externally (e.g. by changing the controlled prop).
+      return;
+    }
+
+    const previousState = getControlledState(internalPreviousState, controlledProps);
+
+    (Object.keys(nextState) as (keyof State)[]).forEach((key) => {
+      // go through all state keys and compare them with the previous state
+      const stateComparer = stateComparers[key] ?? areEqual;
+
+      const nextStateItem = nextState[key];
+      const previousStateItem = previousState[key];
+
+      if (!stateComparer(nextStateItem, previousStateItem)) {
+        onStateChange?.(
+          lastActionRef.current!.event ?? null,
+          key,
+          nextStateItem,
+          lastActionRef.current!.type ?? '',
+          nextState,
+        );
+      }
+    });
+
+    lastActionRef.current = null;
+  }, [
+    internalPreviousState,
+    nextState,
+    lastActionRef,
+    onStateChange,
+    stateComparers,
+    controlledProps,
+  ]);
+}
+
+/**
+ * The alternative to `React.useReducer` that lets you control the state from the outside.
+ *
+ * It can be used in an uncontrolled mode, similar to `React.useReducer`, or in a controlled mode, when the state is controlled by the props.
+ * It also supports partially controlled state, when some state items are controlled and some are not.
+ *
+ * The controlled state items are provided via the `controlledProps` parameter.
+ * When a reducer action is dispatched, the internal state is updated with the new values.
+ * A change event (`onStateChange`) is then triggered (for each changed state item) if the new state is different from the previous state.
+ * This event can be used to update the controlled values.
+ *
+ * The comparison of the previous and next states is done using the `stateComparers` parameter.
+ * If a state item has a corresponding comparer, it will be used to determine if the state has changed.
+ * This is useful when the state item is an object and you want to compare only a subset of its properties or if it's an array and you want to compare its contents.
+ *
+ * An additional feature is the `actionAddOn` parameter. It allows you to add additional properties to every action object.
+ *
+ * @ignore - internal hook.
+ */
+export default function useControllableReducer<
+  State extends {},
+  Action extends ControllableReducerAction,
+  ActionAddOn = {},
+>(
+  parameters: ControllableReducerParameters<State, Action, ActionAddOn>,
+): [State, (action: Action) => void] {
+  const actionRef = React.useRef<Action | null>(null);
+
+  const {
+    reducer,
+    initialState,
+    controlledProps = EMPTY_OBJECT,
+    stateComparers = EMPTY_OBJECT,
+    onStateChange = NOOP,
+    actionAddOn,
+  } = parameters;
+
+  // The reducer that is passed to React.useReducer is wrapped with a function that augments the state with controlled values.
+  const reducerWithControlledState = React.useCallback(
+    (state: State, action: Action & ActionAddOn) => {
+      const controlledState = getControlledState(state, controlledProps);
+      return reducer(controlledState, action);
+    },
+    [controlledProps, reducer],
+  );
+
+  const [nextState, dispatch] = React.useReducer(reducerWithControlledState, initialState);
+
+  // The action that is passed to dispatch is augmented with the actionAddOn.
+  const dispatchWithAddOn = React.useCallback(
+    (action: Action) => {
+      actionRef.current = action;
+      dispatch({
+        ...action,
+        ...actionAddOn,
+      } as Action & ActionAddOn);
+    },
+    [actionAddOn],
+  );
+
+  const previousState = React.useRef<State>(initialState);
+
+  React.useEffect(() => {
+    previousState.current = nextState;
+  }, [nextState]);
+
+  useStateChangeDetection<State>(
+    nextState,
+    previousState.current,
+    stateComparers ?? EMPTY_OBJECT,
+    onStateChange ?? NOOP,
+    controlledProps,
+    actionRef,
+  );
+
+  return [getControlledState(nextState, controlledProps), dispatchWithAddOn];
+}
diff --git a/packages/mui-base/src/utils/useControllableReducer.types.ts b/packages/mui-base/src/utils/useControllableReducer.types.ts
new file mode 100644
index 00000000000000..2576b8cd80e9ac
--- /dev/null
+++ b/packages/mui-base/src/utils/useControllableReducer.types.ts
@@ -0,0 +1,73 @@
+export type StateComparers<State> = {
+  [key in keyof State]?: (value1: State[key], value2: State[key]) => boolean;
+};
+
+export type StateChangeCallback<State> = <StateKey extends keyof State>(
+  event: React.SyntheticEvent | null,
+  field: StateKey,
+  value: State[StateKey],
+  reason: string,
+  state: State,
+) => void;
+
+/**
+ * Parameters of the useControllableReducer hook.
+ */
+export interface ControllableReducerParameters<
+  State,
+  Action extends ControllableReducerAction,
+  ActionAddOn = {},
+> {
+  /**
+   * The reducer function.
+   *
+   * @param state The previous state. If controlledProps are defined, the state will contain the values of the controlledProps.
+   * @param action The action to dispatch. The action can be augmented with the `actionAddOn`.
+   * @returns The updated state.
+   */
+  reducer: (state: State, action: Action & ActionAddOn) => State;
+  /**
+   * The controlled props that will override the state items.
+   */
+  controlledProps?: Partial<State>;
+  /**
+   * The initial state.
+   */
+  initialState: State;
+  /**
+   * Comparers for each state item. If a state item has a corresponding comparer, it will be used to determine if the state has changed.
+   * This is taken into consideration when firing the `onStateChange` event.
+   * If no comparer is defined, the default equality comparison will be used.
+   */
+  stateComparers?: StateComparers<State>;
+  /**
+   * The event handler called whenever a field of the state changes.
+   */
+  onStateChange?: StateChangeCallback<State>;
+  /**
+   * Additional properties that will be added to the action.
+   */
+  actionAddOn?: ActionAddOn;
+}
+
+export const setStateActionType = 'setState';
+
+export interface SetStateAction<State> {
+  type: typeof setStateActionType;
+  event: null;
+  value: Partial<State>;
+}
+
+/*
+ * The standard shape of the action accepted by the controllable reducer
+ */
+export type ControllableReducerAction = {
+  /**
+   * The type of the action.
+   */
+  type?: string;
+  /**
+   * The event that triggered the action.
+   */
+  event?: React.SyntheticEvent | null;
+};
diff --git a/packages/mui-base/src/utils/useLatest.ts b/packages/mui-base/src/utils/useLatest.ts
index dd542da03684c4..5d21dd459a1512 100644
--- a/packages/mui-base/src/utils/useLatest.ts
+++ b/packages/mui-base/src/utils/useLatest.ts
@@ -15,6 +15,7 @@ import * as React from 'react';
  */
 export default function useLatest<T>(value: T, deps?: React.DependencyList) {
   const ref = React.useRef<T>(value);
+  ref.current = value;
 
   React.useEffect(() => {
     ref.current = value;

From 5db7fae7f4d66e64479f34eb2c4f11f28aa579e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 28 Mar 2023 22:31:50 +0200
Subject: [PATCH 09/49] Docs and cleanup of useList

---
 packages/mui-base/src/useList/ListContext.ts  | 17 ++++
 .../mui-base/src/useList/actions.types.ts     | 63 ---------------
 .../src/useList/defaultListboxReducer.test.ts | 40 +++++-----
 .../src/useList/defaultListboxReducer.ts      | 28 +++----
 packages/mui-base/src/useList/index.ts        |  4 +-
 .../mui-base/src/useList/listActions.types.ts | 63 +++++++++++++++
 packages/mui-base/src/useList/useList.ts      | 63 +++++++--------
 .../mui-base/src/useList/useList.types.ts     | 79 +++++++++++++------
 packages/mui-base/src/useList/useListItem.ts  |  8 +-
 .../mui-base/src/useMenu/MenuProvider.tsx     |  2 +-
 packages/mui-base/src/useMenu/useMenu.ts      | 10 +--
 .../mui-base/src/useSelect/SelectProvider.tsx |  2 +-
 packages/mui-base/src/useSelect/useSelect.ts  | 14 ++--
 .../src/useTabsList/TabsListProvider.tsx      |  3 +-
 .../mui-base/src/useTabsList/useTabsList.ts   | 10 +--
 .../src/utils/useControllableReducer.test.tsx |  8 +-
 .../src/utils/useControllableReducer.types.ts |  2 +-
 17 files changed, 231 insertions(+), 185 deletions(-)
 create mode 100644 packages/mui-base/src/useList/ListContext.ts
 delete mode 100644 packages/mui-base/src/useList/actions.types.ts
 create mode 100644 packages/mui-base/src/useList/listActions.types.ts

diff --git a/packages/mui-base/src/useList/ListContext.ts b/packages/mui-base/src/useList/ListContext.ts
new file mode 100644
index 00000000000000..2484d4b3fff371
--- /dev/null
+++ b/packages/mui-base/src/useList/ListContext.ts
@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { ListAction } from './listActions.types';
+import { ListState, ListItemState } from './useList.types';
+
+export interface ListContextValue<ItemValue, State extends ListState<ItemValue>> {
+  dispatch: (action: ListAction<ItemValue, State>) => void;
+  getItemState: (item: ItemValue) => ListItemState;
+  registerHighlightChangeHandler: (handler: (item: ItemValue | null) => void) => () => void;
+  registerSelectionChangeHandler: (
+    handler: (items: ItemValue | ItemValue[] | null) => void,
+  ) => () => void;
+}
+
+export const ListContext = React.createContext<ListContextValue<any, any> | null>(null);
+if (process.env.NODE_ENV !== 'production') {
+  ListContext.displayName = 'ListContext';
+}
diff --git a/packages/mui-base/src/useList/actions.types.ts b/packages/mui-base/src/useList/actions.types.ts
deleted file mode 100644
index 4a6f5547c9950a..00000000000000
--- a/packages/mui-base/src/useList/actions.types.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import { SetStateAction, setStateActionType } from '../utils/useControllableReducer.types';
-import type { ListState } from './useList.types';
-
-export const ActionTypes = {
-  blur: 'blur',
-  focus: 'focus',
-  keyDown: 'keyDown',
-  itemClick: 'itemClick',
-  itemHover: 'itemHover',
-  itemsChange: 'itemsChange',
-  setState: setStateActionType,
-  textNavigation: 'textNavigation',
-} as const;
-
-interface ItemClickAction<Value> {
-  type: typeof ActionTypes.itemClick;
-  item: Value;
-  event: React.MouseEvent;
-}
-
-interface ItemHoverAction<Value> {
-  type: typeof ActionTypes.itemHover;
-  item: Value;
-  event: React.MouseEvent;
-}
-
-interface FocusAction {
-  type: typeof ActionTypes.focus;
-  event: React.FocusEvent;
-}
-
-interface BlurAction {
-  type: typeof ActionTypes.blur;
-  event: React.FocusEvent;
-}
-
-interface KeyDownAction {
-  type: typeof ActionTypes.keyDown;
-  event: React.KeyboardEvent;
-}
-
-interface TextNavigationAction {
-  type: typeof ActionTypes.textNavigation;
-  event: React.KeyboardEvent;
-  searchString: string;
-}
-
-interface ItemsChangeAction<Value> {
-  type: typeof ActionTypes.itemsChange;
-  event: null;
-  items: Value[];
-  previousItems: Value[];
-}
-
-export type ListAction<Value, State extends ListState<Value>> =
-  | BlurAction
-  | FocusAction
-  | ItemClickAction<Value>
-  | ItemHoverAction<Value>
-  | ItemsChangeAction<Value>
-  | KeyDownAction
-  | SetStateAction<State>
-  | TextNavigationAction;
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.test.ts b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
index 6396990767aa48..ff9b3605764e87 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.test.ts
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { ListReducerAction, ListState } from './useList.types';
-import { ActionTypes } from './actions.types';
+import { ListActionTypes } from './listActions.types';
 import defaultReducer from './defaultListboxReducer';
 
 describe('useListbox defaultReducer', () => {
@@ -13,7 +13,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.setState,
+        type: ListActionTypes.setState,
         value: { selectedValues: ['foo'] },
         event: null,
         props: {
@@ -43,7 +43,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.blur,
+        type: ListActionTypes.blur,
         event: {} as any, // not relevant
         props: {
           current: {
@@ -73,7 +73,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.itemClick,
+        type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
           current: {
@@ -102,7 +102,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.itemClick,
+        type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
           current: {
@@ -131,7 +131,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.itemClick,
+        type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
           current: {
@@ -160,7 +160,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.itemClick,
+        type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         props: {
           current: {
@@ -192,7 +192,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'Home',
           } as any,
@@ -224,7 +224,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'End',
           } as any,
@@ -256,7 +256,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'ArrowUp',
           } as any,
@@ -288,7 +288,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
@@ -318,7 +318,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'ArrowDown',
           } as any,
@@ -350,7 +350,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
@@ -380,7 +380,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.keyDown,
+          type: ListActionTypes.keyDown,
           event: {
             key: 'Enter',
           } as any,
@@ -410,7 +410,7 @@ describe('useListbox defaultReducer', () => {
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ActionTypes.itemClick,
+          type: ListActionTypes.itemClick,
           event: {
             key: 'Enter',
           } as any,
@@ -444,7 +444,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.textNavigation,
+        type: ListActionTypes.textNavigation,
         searchString: 'th',
         event: {} as React.KeyboardEvent,
         props: {
@@ -473,7 +473,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.textNavigation,
+        type: ListActionTypes.textNavigation,
         searchString: 'z',
         event: {} as React.KeyboardEvent,
         props: {
@@ -502,7 +502,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.textNavigation,
+        type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
@@ -531,7 +531,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.textNavigation,
+        type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
         props: {
@@ -560,7 +560,7 @@ describe('useListbox defaultReducer', () => {
       };
 
       const action: ListReducerAction<string, ListState<string>> = {
-        type: ActionTypes.textNavigation,
+        type: ListActionTypes.textNavigation,
         searchString: 'one',
         event: {} as React.KeyboardEvent,
         props: {
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.ts b/packages/mui-base/src/useList/defaultListboxReducer.ts
index 3be1fae35cc1c3..037a7269b54728 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useList/defaultListboxReducer.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { ActionTypes } from './actions.types';
+import { ListActionTypes } from './listActions.types';
 import {
   ListState,
-  UseListParametersWithDefaults,
+  ListActionAddOnValue,
   ListReducerAction,
   ListActionAddOn,
 } from './useList.types';
@@ -132,7 +132,7 @@ function getNewHighlightedItem<ItemValue>(
 function moveHighlight<ItemValue>(
   previouslyHighlightedValue: ItemValue | null,
   diff: number | 'reset' | 'start' | 'end',
-  props: UseListParametersWithDefaults<ItemValue>,
+  props: ListActionAddOnValue<ItemValue>,
 ) {
   const { items, isItemDisabled, disableListWrap, disabledItemsFocusable, itemComparer } = props;
 
@@ -186,7 +186,7 @@ function toggleSelection<ItemValue>(
 function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
   item: ItemValue,
   state: State,
-  props: UseListParametersWithDefaults<ItemValue>,
+  props: ListActionAddOnValue<ItemValue>,
 ): State {
   const { itemComparer = (o, v) => o === v, isItemDisabled = () => false, selectionLimit } = props;
   const { selectedValues } = state;
@@ -210,7 +210,7 @@ function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
 function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
   event: React.KeyboardEvent,
   state: State,
-  parameters: UseListParametersWithDefaults<ItemValue>,
+  parameters: ListActionAddOnValue<ItemValue>,
 ): State {
   const previouslySelectedValue = state.highlightedValue;
   const { orientation } = parameters;
@@ -303,7 +303,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
 function handleBlur<ItemValue, State extends ListState<ItemValue>>(
   state: State,
-  props: UseListParametersWithDefaults<ItemValue>,
+  props: ListActionAddOnValue<ItemValue>,
 ): State {
   if (props.focusManagement === 'DOM') {
     return state;
@@ -333,7 +333,7 @@ function textCriteriaMatches<ItemValue>(
 function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
   state: State,
   searchString: string,
-  props: UseListParametersWithDefaults<ItemValue>,
+  props: ListActionAddOnValue<ItemValue>,
 ): State {
   const {
     items,
@@ -395,7 +395,7 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
   items: ItemValue[],
   previousItems: ItemValue[],
   state: State,
-  props: UseListParametersWithDefaults<ItemValue>,
+  props: ListActionAddOnValue<ItemValue>,
 ): State {
   const { itemComparer, focusManagement } = props;
 
@@ -429,20 +429,20 @@ export default function defaultListboxReducer<ItemValue, State extends ListState
   const parameters = props.current!;
 
   switch (type) {
-    case ActionTypes.keyDown:
+    case ListActionTypes.keyDown:
       return handleKeyDown(action.event, state, parameters);
-    case ActionTypes.itemClick:
+    case ListActionTypes.itemClick:
       return handleItemSelection(action.item, state, parameters);
-    case ActionTypes.blur:
+    case ListActionTypes.blur:
       return handleBlur(state, parameters);
-    case ActionTypes.setState:
+    case ListActionTypes.setState:
       return {
         ...state,
         ...action.value,
       };
-    case ActionTypes.textNavigation:
+    case ListActionTypes.textNavigation:
       return handleTextNavigation(state, action.searchString, parameters);
-    case ActionTypes.itemsChange:
+    case ListActionTypes.itemsChange:
       return handleItemsChange(action.items, action.previousItems, state, parameters);
     default:
       return state;
diff --git a/packages/mui-base/src/useList/index.ts b/packages/mui-base/src/useList/index.ts
index 0a0c22633334cc..f006e5a7cf6e08 100644
--- a/packages/mui-base/src/useList/index.ts
+++ b/packages/mui-base/src/useList/index.ts
@@ -7,4 +7,6 @@ export * from './useListItem.types';
 
 export { default as defaultListboxReducer } from './defaultListboxReducer';
 
-export * from './actions.types';
+export * from './listActions.types';
+
+export * from './ListContext';
diff --git a/packages/mui-base/src/useList/listActions.types.ts b/packages/mui-base/src/useList/listActions.types.ts
new file mode 100644
index 00000000000000..89c98d38154ec8
--- /dev/null
+++ b/packages/mui-base/src/useList/listActions.types.ts
@@ -0,0 +1,63 @@
+import { SetStateAction, setStateActionType } from '../utils/useControllableReducer.types';
+import type { ListState } from './useList.types';
+
+export const ListActionTypes = {
+  blur: 'list:blur',
+  focus: 'list:focus',
+  keyDown: 'list:keyDown',
+  itemClick: 'list:itemClick',
+  itemHover: 'list:itemHover',
+  itemsChange: 'list:itemsChange',
+  setState: setStateActionType,
+  textNavigation: 'list:textNavigation',
+} as const;
+
+interface ItemClickAction<ItemValue> {
+  type: typeof ListActionTypes.itemClick;
+  item: ItemValue;
+  event: React.MouseEvent;
+}
+
+interface ItemHoverAction<ItemValue> {
+  type: typeof ListActionTypes.itemHover;
+  item: ItemValue;
+  event: React.MouseEvent;
+}
+
+interface FocusAction {
+  type: typeof ListActionTypes.focus;
+  event: React.FocusEvent;
+}
+
+interface BlurAction {
+  type: typeof ListActionTypes.blur;
+  event: React.FocusEvent;
+}
+
+interface KeyDownAction {
+  type: typeof ListActionTypes.keyDown;
+  event: React.KeyboardEvent;
+}
+
+interface TextNavigationAction {
+  type: typeof ListActionTypes.textNavigation;
+  event: React.KeyboardEvent;
+  searchString: string;
+}
+
+interface ItemsChangeAction<ItemValue> {
+  type: typeof ListActionTypes.itemsChange;
+  event: null;
+  items: ItemValue[];
+  previousItems: ItemValue[];
+}
+
+export type ListAction<ItemValue, State extends ListState<ItemValue>> =
+  | BlurAction
+  | FocusAction
+  | ItemClickAction<ItemValue>
+  | ItemHoverAction<ItemValue>
+  | ItemsChangeAction<ItemValue>
+  | KeyDownAction
+  | SetStateAction<State>
+  | TextNavigationAction;
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 16ca8d23005720..6b71442cf7b8e3 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -2,52 +2,43 @@ import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import {
   UseListParameters,
-  UseListParametersWithDefaults,
+  ListActionAddOnValue,
   ListItemState,
   UseListRootSlotProps,
   ListState,
   ListActionAddOn,
 } from './useList.types';
+import { ListActionTypes, ListAction } from './listActions.types';
+import { ListContextValue } from './ListContext';
 import defaultReducer from './defaultListboxReducer';
-import useControllableReducer from '../utils/useControllableReducer';
-import areArraysEqual from '../utils/areArraysEqual';
-import { EventHandlers } from '../utils/types';
-import useLatest from '../utils/useLatest';
-import useTextNavigation from '../utils/useTextNavigation';
 import useListChangeNotifiers from './useListChangeNotifiers';
-import { ActionTypes, ListAction } from './actions.types';
+import useControllableReducer from '../utils/useControllableReducer';
 import {
   ControllableReducerAction,
   StateChangeCallback,
   StateComparers,
 } from '../utils/useControllableReducer.types';
+import areArraysEqual from '../utils/areArraysEqual';
+import { EventHandlers } from '../utils/types';
+import useLatest from '../utils/useLatest';
+import useTextNavigation from '../utils/useTextNavigation';
+
+const EMPTY_OBJECT = {};
+const NOOP = () => {};
 
-const noop = () => {};
-const emptyObject = {};
+const defaultItemComparer = <ItemValue>(optionA: ItemValue, optionB: ItemValue) =>
+  optionA === optionB;
 
-const defaultItemComparer = <TOption>(optionA: TOption, optionB: TOption) => optionA === optionB;
 const defaultIsItemDisabled = () => false;
+
 const defaultItemStringifier = <ItemValue>(item: ItemValue) =>
   typeof item === 'string' ? item : String(item);
+
 const defaultGetInitialState = () => ({
   highlightedValue: null,
   selectedValues: [],
 });
 
-export interface ListContextValue<ItemValue, State extends ListState<ItemValue>> {
-  dispatch: (action: ListAction<ItemValue, State>) => void;
-  getItemState: (item: ItemValue) => ListItemState;
-  registerHighlightChangeHandler: (handler: (item: ItemValue | null) => void) => () => void;
-  registerSelectionChangeHandler: (
-    handler: (items: ItemValue | ItemValue[] | null) => void,
-  ) => () => void;
-}
-
-export const ListContext = React.createContext<ListContextValue<any, any> | null>(null);
-if (process.env.NODE_ENV !== 'production') {
-  ListContext.displayName = 'ListContext';
-}
-
 /**
  * The useList is a lower-level utility that is used to build list-like components.
  * It's used to manage the state of the list and its items.
@@ -62,7 +53,7 @@ function useList<
   CustomAction extends ControllableReducerAction = never,
 >(params: UseListParameters<ItemValue, State, CustomAction>) {
   const {
-    controlledState: controlledProps = emptyObject,
+    controlledProps = EMPTY_OBJECT,
     disabledItemsFocusable = false,
     disableListWrap = false,
     focusManagement = 'activeDescendant',
@@ -71,7 +62,7 @@ function useList<
     getItemId,
     isItemDisabled = defaultIsItemDisabled,
     listRef: externalListRef,
-    onStateChange = noop,
+    onStateChange = NOOP,
     items,
     itemComparer = defaultItemComparer,
     itemStringifier = defaultItemStringifier,
@@ -110,9 +101,9 @@ function useList<
       if (
         focusManagement === 'DOM' &&
         value != null &&
-        (reason === ActionTypes.itemClick ||
-          reason === ActionTypes.keyDown ||
-          reason === ActionTypes.textNavigation)
+        (reason === ListActionTypes.itemClick ||
+          reason === ListActionTypes.keyDown ||
+          reason === ListActionTypes.textNavigation)
       ) {
         getItemDomElement?.(value)?.focus();
       }
@@ -156,7 +147,7 @@ function useList<
     [handleHighlightChange, onChange, onStateChange],
   );
 
-  const propsWithDefaults: React.RefObject<UseListParametersWithDefaults<ItemValue>> = useLatest(
+  const propsWithDefaults: React.RefObject<ListActionAddOnValue<ItemValue>> = useLatest(
     {
       disabledItemsFocusable,
       disableListWrap,
@@ -200,7 +191,7 @@ function useList<
 
   const handleTextNavigation = useTextNavigation((searchString, event) =>
     dispatch({
-      type: ActionTypes.textNavigation,
+      type: ListActionTypes.textNavigation,
       event,
       searchString,
     }),
@@ -223,7 +214,7 @@ function useList<
     }
 
     dispatch({
-      type: ActionTypes.itemsChange,
+      type: ListActionTypes.itemsChange,
       event: null,
       items,
       previousItems: previousItems.current,
@@ -250,7 +241,7 @@ function useList<
   const setSelectedValue = React.useCallback(
     (values: ItemValue[]) => {
       dispatch({
-        type: ActionTypes.setState,
+        type: ListActionTypes.setState,
         event: null,
         value: { selectedValues: values } as Partial<State>,
       });
@@ -261,7 +252,7 @@ function useList<
   const setHighlightedValue = React.useCallback(
     (item: ItemValue | null) => {
       dispatch({
-        type: ActionTypes.setState,
+        type: ListActionTypes.setState,
         event: null,
         value: { highlightedValue: item } as Partial<State>,
       });
@@ -299,7 +290,7 @@ function useList<
       }
 
       dispatch({
-        type: ActionTypes.keyDown,
+        type: ListActionTypes.keyDown,
         event,
       });
 
@@ -320,7 +311,7 @@ function useList<
       }
 
       dispatch({
-        type: ActionTypes.blur,
+        type: ListActionTypes.blur,
         event,
       });
     };
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 52c62dca2a1ec1..dcb2c4290e69b0 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -1,12 +1,12 @@
 import * as React from 'react';
 import { Simplify } from '@mui/types';
-import { ListAction } from './actions.types';
+import { ListAction } from './listActions.types';
 import {
   ControllableReducerAction,
   StateChangeCallback,
 } from '../utils/useControllableReducer.types';
 
-type UseListParametersWithDefaultsRequiredKeys =
+type ListActionAddOnValueRequiredKeys =
   | 'disabledItemsFocusable'
   | 'disableListWrap'
   | 'focusManagement'
@@ -17,25 +17,32 @@ type UseListParametersWithDefaultsRequiredKeys =
   | 'orientation'
   | 'selectionLimit';
 
-export type UseListParametersWithDefaults<ItemValue> = Simplify<
-  Required<Pick<UseListParameters<ItemValue, any, any>, UseListParametersWithDefaultsRequiredKeys>>
+/**
+ * The subset of `UseListParameters` that is passed to the list reducer actions.
+ */
+export type ListActionAddOnValue<ItemValue> = Simplify<
+  Required<Pick<UseListParameters<ItemValue, any, any>, ListActionAddOnValueRequiredKeys>>
 >;
 
-export type FocusManagementType = 'DOM' | 'activeDescendant';
-
 export type ListReducerAction<ItemValue, State extends ListState<ItemValue>> = ListAction<
   ItemValue,
   State
 > & {
-  props: React.RefObject<UseListParametersWithDefaults<ItemValue>>;
+  props: React.RefObject<ListActionAddOnValue<ItemValue>>;
 };
 
 export type ListActionAddOn<ItemValue> = {
-  props: React.RefObject<UseListParametersWithDefaults<ItemValue>>;
+  props: React.RefObject<ListActionAddOnValue<ItemValue>>;
 };
 
 export interface ListState<ItemValue> {
+  /**
+   * The item that is currently highlighted.
+   */
   highlightedValue: ItemValue | null;
+  /**
+   * The item(s) that are currently selected.
+   */
   selectedValues: ItemValue[];
 }
 
@@ -44,12 +51,20 @@ export type ListReducer<ItemValue, State extends ListState<ItemValue>> = (
   action: ListReducerAction<ItemValue, State>,
 ) => State;
 
+export type FocusManagementType = 'DOM' | 'activeDescendant';
+
 export interface UseListParameters<
   ItemValue,
   State extends ListState<ItemValue> = ListState<ItemValue>,
   CustomAction extends ControllableReducerAction = never,
 > {
-  controlledState?: Partial<State>;
+  /**
+   * The externally controlled values (highlighted and selected item(s)) of the list.
+   * If a custom state is used, this object can contain the added state fields as well.
+   *
+   * @default {}
+   */
+  controlledProps?: Partial<State>;
   /**
    * If `true`, it will be possible to highlight disabled items.
    * @default false
@@ -60,21 +75,32 @@ export interface UseListParameters<
    * @default false
    */
   disableListWrap?: boolean;
+  /**
+   * The focus management strategy used by the list.
+   * Controls the attributes used to set focus on the list items.
+   */
   focusManagement?: FocusManagementType;
   /**
    * A function that returns the DOM element associated with an item.
-   * This is required to set focus when using the `DOM` focus management.
+   * This is required when using the `DOM` focus management.
    *
    * @param item List item to get the DOM element for.
    */
   getItemDomElement?: (itemValue: ItemValue) => HTMLElement | null;
   /**
    * A function that returns the id of an item.
-   * This is required to set `aria-activedescendant` and is required when using the `activeDescendant` focus management.
+   * This is required when using the `activeDescendant` focus management.
    *
    * @param itemValue List item to get the id for.
    */
   getItemId?: (itemValue: ItemValue) => string | undefined;
+  /**
+   * A function that intializes the state of the list.
+   * It is required when using a custom state with mandatory fields.
+   * If not provided, the state will be initialized with the default values (nothing highlighted or selected).
+   *
+   * @returns The initial state of the list.
+   */
   getInitialState?: () => State;
   /**
    * A function that determines if a particular item is disabled.
@@ -86,7 +112,8 @@ export interface UseListParameters<
    */
   listRef?: React.Ref<any>;
   /**
-   * Callback fired when the value changes.
+   * Callback fired when the selected value changes.
+   * This is a strongly typed convenience event that can be used instead of `onStateChange`.
    */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
@@ -95,6 +122,7 @@ export interface UseListParameters<
   ) => void;
   /**
    * Callback fired when the highlighted option changes.
+   * This is a strongly typed convenience event that can be used instead of `onStateChange`.
    */
   onHighlightChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
@@ -102,22 +130,16 @@ export interface UseListParameters<
     reason: string,
   ) => void;
   /**
-   * Callback fired when the selected value changes.
+   * Callback fired when the any of the state items change.
+   * Note that in case of `selectedValues` and `highlightedValue` the strongly typed
+   * `onChange` and `onHighlightChange` callbacks are also fired.
    */
   onStateChange?: StateChangeCallback<State>;
-  /**
-   * Callback fired when the highlighted item changes.
-   * The `value` is null if there is no highlighted item.
-   */
   /**
    * A function that tests equality between two items' values.
    * @default (a, b) => a === b
    */
   itemComparer?: (itemValue1: ItemValue, itemValue2: ItemValue) => boolean;
-  /**
-   * A function that generates the id attribute of individual options.
-   */
-  itemIdGenerator?: (value: ItemValue, index: number) => string;
   /**
    * A function that converts an object to its string representation
    * @default (o) => o
@@ -131,6 +153,7 @@ export interface UseListParameters<
    * Orientation of the items in the list.
    * Determines the actions that are performed when arrow keys are pressed.
    */
+  // TODO: add vertical-reverse
   orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
   /**
    * Maximum number of items that can be selected at once.
@@ -140,7 +163,7 @@ export interface UseListParameters<
    */
   selectionLimit?: number | null;
   /**
-   * Custom state reducer function. It calculates the new state (highlighted and selected items)
+   * Custom state reducer function. It calculates the new state (highlighted and selected items + optional custom state)
    * based on the previous one and the performed action.
    */
   stateReducer?: (
@@ -150,14 +173,26 @@ export interface UseListParameters<
 }
 
 export interface ListItemState {
+  /**
+   * If `true` the item is disabled.
+   */
   disabled: boolean;
   /**
    * Determines if the item is focusable.
    * If `undefined`, focusing doesn't apply as focusManagement is set to 'activeDescendant'.
    */
   focusable: boolean | undefined;
+  /**
+   * If `true` the item is highlighted.
+   */
   highlighted: boolean;
+  /**
+   * The 0-based index of the item.
+   */
   index: number;
+  /**
+   * If `true` the item is selected.
+   */
   selected: boolean;
 }
 
diff --git a/packages/mui-base/src/useList/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
index 420cb2552a29b3..318dc33b43ffe4 100644
--- a/packages/mui-base/src/useList/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -5,9 +5,9 @@ import {
 } from '@mui/utils';
 import { EventHandlers } from '../utils/types';
 import useForcedRerendering from '../utils/useForcedRerendering';
-import { ListContext } from './useList';
 import { UseListItemParameters, UseListItemReturnValue } from './useListItem.types';
-import { ActionTypes } from './actions.types';
+import { ListActionTypes } from './listActions.types';
+import { ListContext } from './ListContext';
 
 /**
  * Contains the logic for an item of a list-like component (e.g. Select, Menu, etc.).
@@ -72,7 +72,7 @@ export default function useListItem<ItemValue>(
       event.preventDefault();
 
       dispatch({
-        type: ActionTypes.itemClick,
+        type: ListActionTypes.itemClick,
         item,
         event,
       });
@@ -88,7 +88,7 @@ export default function useListItem<ItemValue>(
       }
 
       dispatch({
-        type: ActionTypes.itemHover,
+        type: ListActionTypes.itemHover,
         item,
         event,
       });
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
index d7e2c4d97c5b2c..fd01974dcda40d 100644
--- a/packages/mui-base/src/useMenu/MenuProvider.tsx
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
+import { ListContext, ListContextValue } from '../useList/ListContext';
 import { MenuItemMetadata } from '../useMenuItem';
-import { ListContext, ListContextValue } from '../useList';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 import type { MenuInternalState } from './useMenu.types';
 
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index d9b75bcc449305..618d5a525d2f9f 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import useList, {
   defaultListboxReducer,
-  ActionTypes,
+  ListActionTypes,
   ListActionAddOn,
   ListAction,
 } from '../useList';
@@ -56,7 +56,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
       state: MenuInternalState,
       action: ListAction<string, MenuInternalState> & ListActionAddOn<string>,
     ): MenuInternalState => {
-      if (action.type === ActionTypes.itemHover || action.type === ActionTypes.setState) {
+      if (action.type === ListActionTypes.itemHover || action.type === ListActionTypes.setState) {
         return state;
       }
 
@@ -70,7 +70,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
         };
       }
 
-      if (action.type === ActionTypes.keyDown) {
+      if (action.type === ListActionTypes.keyDown) {
         if (action.event.key === 'Escape') {
           return {
             ...newState,
@@ -79,7 +79,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
         }
       }
 
-      if (action.type === ActionTypes.blur) {
+      if (action.type === ListActionTypes.blur) {
         if (!listboxRef.current?.contains(action.event.relatedTarget)) {
           return {
             ...newState,
@@ -114,7 +114,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     contextValue: listContextValue,
     state: { open },
   } = useList<string, MenuInternalState>({
-    controlledState,
+    controlledProps: controlledState,
     disabledItemsFocusable: true,
     focusManagement: 'DOM',
     getItemDomElement,
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
index 1f162e9383879b..d07afe33173c89 100644
--- a/packages/mui-base/src/useSelect/SelectProvider.tsx
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { ListContext, ListContextValue } from '../useList';
+import { ListContextValue, ListContext } from '../useList/ListContext';
 import { SelectOption } from '../useOption/useOption.types';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 import type { SelectInternalState } from './useSelect.types';
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 19b5bdef942b05..64e32905ec48dc 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -18,7 +18,7 @@ import {
 } from './useSelect.types';
 import useList, {
   defaultListboxReducer,
-  ActionTypes,
+  ListActionTypes,
   UseListParameters,
   ListAction,
   ListActionAddOn,
@@ -165,7 +165,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
       );
 
       switch (action.type) {
-        case ActionTypes.keyDown:
+        case ListActionTypes.keyDown:
           // change selection when listbox is closed
           if (
             (action.event.key === 'ArrowUp' || action.event.key === 'ArrowDown') &&
@@ -192,7 +192,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
           break;
 
-        case ActionTypes.itemClick:
+        case ListActionTypes.itemClick:
           if (!multiple) {
             return {
               ...newState,
@@ -202,15 +202,15 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
           break;
 
-        case ActionTypes.setState:
-        case ActionTypes.itemsChange:
+        case ListActionTypes.setState:
+        case ListActionTypes.itemsChange:
           return {
             ...newState,
             highlightedValue:
               newState.selectedValues.length > 0 ? newState.selectedValues[0] : null,
           };
 
-        case ActionTypes.blur:
+        case ListActionTypes.blur:
           return {
             ...newState,
             highlightedValue:
@@ -277,7 +277,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
       open: false,
     }),
     getItemId: (itemValue) => options.get(itemValue)?.id,
-    controlledState,
+    controlledProps: controlledState,
     isItemDisabled,
     listRef: handleListboxRef,
     onChange: (e, newValues) => {
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index 245db3a65ee3e2..b5818a2cf0c771 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react';
-import { ListContext, ListContextValue, ListState } from '../useList';
+import { ListState } from '../useList';
+import { ListContextValue, ListContext } from '../useList/ListContext';
 import { TabMetadata } from '../useTabs/useTabs';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index f35c8cd48c90e0..f67b9ee94a25a6 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -10,7 +10,7 @@ import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
 import useList, {
-  ActionTypes,
+  ListActionTypes,
   defaultListboxReducer,
   ListReducer,
   ListState,
@@ -72,14 +72,14 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     (state, action) => {
       const newState = defaultListboxReducer(state, action);
 
-      if (action.type === ActionTypes.itemsChange) {
+      if (action.type === ListActionTypes.itemsChange) {
         return {
           ...newState,
           highlightedValue: newState.selectedValues[0] ?? null,
         };
       }
 
-      if (action.type === ActionTypes.setState && action.value.selectedValues != null) {
+      if (action.type === ListActionTypes.setState && action.value.selectedValues != null) {
         return {
           ...newState,
           highlightedValue: action.value.selectedValues[0],
@@ -127,7 +127,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     highlightedOption,
     selectedOptions,
   } = useList({
-    controlledState,
+    controlledProps: controlledState,
     disabledItemsFocusable: !selectionFollowsFocus,
     focusManagement: 'DOM',
     getItemDomElement: getTabElement,
@@ -147,7 +147,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
 
     if (value != null) {
       dispatch({
-        type: ActionTypes.setState,
+        type: ListActionTypes.setState,
         event: null,
         value: {
           highlightedValue: value,
diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
index 7b5fa114194559..d4d8b4386c509d 100644
--- a/packages/mui-base/src/utils/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -249,8 +249,8 @@ describe('useControllableReducer', () => {
         };
       });
 
-      const actionToDispatch = {
-        type: 'setState' as const,
+      const actionToDispatch: SetStateAction<TestState> = {
+        type: setStateActionType,
         event: null,
         value: { productionYear: 2010 },
       };
@@ -291,8 +291,8 @@ describe('useControllableReducer', () => {
         };
       };
 
-      const actionToDispatch = {
-        type: 'setState' as const,
+      const actionToDispatch: SetStateAction<TestState> = {
+        type: setStateActionType,
         event: null,
         value: { productionYear: 2010, make: 'BMW' },
       };
diff --git a/packages/mui-base/src/utils/useControllableReducer.types.ts b/packages/mui-base/src/utils/useControllableReducer.types.ts
index 2576b8cd80e9ac..cbbbae8381c3e4 100644
--- a/packages/mui-base/src/utils/useControllableReducer.types.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.types.ts
@@ -50,7 +50,7 @@ export interface ControllableReducerParameters<
   actionAddOn?: ActionAddOn;
 }
 
-export const setStateActionType = 'setState';
+export const setStateActionType = 'controlledReducer:setState';
 
 export interface SetStateAction<State> {
   type: typeof setStateActionType;

From 776be3eff049557e51a74fbb5e7ad3ddae4630ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 28 Mar 2023 23:11:15 +0200
Subject: [PATCH 10/49] Rename defaultListboxReducer to listReducer

---
 packages/mui-base/src/useList/index.ts        |   3 +-
 ...boxReducer.test.ts => listReducer.test.ts} |  42 +++---
 ...efaultListboxReducer.ts => listReducer.ts} | 125 +++++++++---------
 packages/mui-base/src/useList/useList.ts      |   2 +-
 packages/mui-base/src/useMenu/useMenu.ts      |   9 +-
 packages/mui-base/src/useSelect/useSelect.ts  |   4 +-
 .../mui-base/src/useTabsList/useTabsList.ts   |   5 +-
 7 files changed, 88 insertions(+), 102 deletions(-)
 rename packages/mui-base/src/useList/{defaultListboxReducer.test.ts => listReducer.test.ts} (94%)
 rename packages/mui-base/src/useList/{defaultListboxReducer.ts => listReducer.ts} (82%)

diff --git a/packages/mui-base/src/useList/index.ts b/packages/mui-base/src/useList/index.ts
index f006e5a7cf6e08..0ec25716f35ac3 100644
--- a/packages/mui-base/src/useList/index.ts
+++ b/packages/mui-base/src/useList/index.ts
@@ -1,11 +1,10 @@
 export { default } from './useList';
-export * from './useList';
 export * from './useList.types';
 
 export { default as useListItem } from './useListItem';
 export * from './useListItem.types';
 
-export { default as defaultListboxReducer } from './defaultListboxReducer';
+export { default as listReducer } from './listReducer';
 
 export * from './listActions.types';
 
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
similarity index 94%
rename from packages/mui-base/src/useList/defaultListboxReducer.test.ts
rename to packages/mui-base/src/useList/listReducer.test.ts
index ff9b3605764e87..e9835ba7a6e7be 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -1,10 +1,10 @@
 import * as React from 'react';
 import { expect } from 'chai';
+import listReducer from './listReducer';
 import { ListReducerAction, ListState } from './useList.types';
 import { ListActionTypes } from './listActions.types';
-import defaultReducer from './defaultListboxReducer';
 
-describe('useListbox defaultReducer', () => {
+describe('listReducer', () => {
   describe('action: setControlledValue', () => {
     it("assigns the provided value to the state's selectedValues", () => {
       const state: ListState<string> = {
@@ -30,7 +30,7 @@ describe('useListbox defaultReducer', () => {
           },
         },
       };
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.selectedValues).to.deep.equal(['foo']);
     });
   });
@@ -60,7 +60,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal(null);
     });
   });
@@ -91,7 +91,7 @@ describe('useListbox defaultReducer', () => {
         item: 'two',
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.selectedValues).to.deep.equal(['two']);
     });
 
@@ -120,7 +120,7 @@ describe('useListbox defaultReducer', () => {
         item: 'two',
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.selectedValues).to.deep.equal(['two']);
     });
 
@@ -149,7 +149,7 @@ describe('useListbox defaultReducer', () => {
         item: 'two',
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.selectedValues).to.deep.equal(['one', 'two']);
     });
 
@@ -178,7 +178,7 @@ describe('useListbox defaultReducer', () => {
         item: 'two',
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.selectedValues).to.deep.equal(['one']);
     });
   });
@@ -211,7 +211,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.highlightedValue).to.equal('two');
       });
     });
@@ -243,7 +243,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.highlightedValue).to.equal('four');
       });
     });
@@ -275,7 +275,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.highlightedValue).to.equal('four');
       });
     });
@@ -307,7 +307,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.highlightedValue).to.equal('two');
       });
 
@@ -337,7 +337,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.highlightedValue).to.equal(null);
       });
     });
@@ -369,7 +369,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
@@ -399,7 +399,7 @@ describe('useListbox defaultReducer', () => {
           },
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
@@ -430,7 +430,7 @@ describe('useListbox defaultReducer', () => {
           item: 'two',
         };
 
-        const result = defaultReducer(state, action);
+        const result = listReducer(state, action);
         expect(result.selectedValues).to.deep.equal(['one', 'two']);
       });
     });
@@ -462,7 +462,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal('three');
     });
 
@@ -491,7 +491,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal('one');
     });
 
@@ -520,7 +520,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal('three');
     });
 
@@ -549,7 +549,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal('two');
     });
 
@@ -578,7 +578,7 @@ describe('useListbox defaultReducer', () => {
         },
       };
 
-      const result = defaultReducer(state, action);
+      const result = listReducer(state, action);
       expect(result.highlightedValue).to.equal('three');
     });
   });
diff --git a/packages/mui-base/src/useList/defaultListboxReducer.ts b/packages/mui-base/src/useList/listReducer.ts
similarity index 82%
rename from packages/mui-base/src/useList/defaultListboxReducer.ts
rename to packages/mui-base/src/useList/listReducer.ts
index 037a7269b54728..343f9d24144f1b 100644
--- a/packages/mui-base/src/useList/defaultListboxReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -12,11 +12,22 @@ type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 // TODO: make page size configurable
 const pageSize = 5;
 
+/**
+ * Looks up the next valid item to highlight within the list.
+ *
+ * @param currentIndex The index of the start of the search.
+ * @param lookupDirection Whether to look for the next or previous item.
+ * @param items The array of items to search.
+ * @param includeDisabledItems Whether to include disabled items in the search.
+ * @param isItemDisabled A function that determines whether an item is disabled.
+ * @param wrapAround Whether to wrap around the list when searching.
+ * @returns
+ */
 function findValidItemToHighlight<ItemValue>(
-  index: number,
+  currentIndex: number,
   lookupDirection: 'next' | 'previous',
   items: ItemValue[],
-  focusDisabled: boolean,
+  includeDisabledItems: boolean,
   isItemDisabled: ItemPredicate<ItemValue>,
   wrapAround: boolean,
 ): number {
@@ -24,7 +35,7 @@ function findValidItemToHighlight<ItemValue>(
     return -1;
   }
 
-  let nextFocus = index;
+  let nextFocus = currentIndex;
 
   for (;;) {
     // No valid items found
@@ -35,7 +46,9 @@ function findValidItemToHighlight<ItemValue>(
       return -1;
     }
 
-    const nextFocusDisabled = focusDisabled ? false : isItemDisabled(items[nextFocus], nextFocus);
+    const nextFocusDisabled = includeDisabledItems
+      ? false
+      : isItemDisabled(items[nextFocus], nextFocus);
     if (nextFocusDisabled) {
       nextFocus += lookupDirection === 'next' ? 1 : -1;
       if (wrapAround) {
@@ -47,17 +60,29 @@ function findValidItemToHighlight<ItemValue>(
   }
 }
 
-function getNewHighlightedItem<ItemValue>(
-  items: ItemValue[],
+// TODO: expose these functions for use in custom reducers
+
+/**
+ * Gets the next item to highlight based on the current highlighted item and the search direction.
+ *
+ * @param previouslyHighlightedValue The item from which to start the search for the next candidate.
+ * @param offset The offset from the previously highlighted item to search for the next candidate or a special named value ('reset', 'start', 'end').
+ * @param props
+ *
+ * @returns The next item to highlight or null if no item is valid.
+ */
+function moveHighlight<ItemValue>(
   previouslyHighlightedValue: ItemValue | null,
-  diff: number | 'reset' | 'start' | 'end',
-  highlightDisabledItems: boolean,
-  isItemDisabled: ItemPredicate<ItemValue>,
-  disableListWrap: boolean,
-  itemComparer: (item1: ItemValue, item2: ItemValue) => boolean,
-): ItemValue | null {
-  const maxIndex = items.length - 1;
+  offset: number | 'reset' | 'start' | 'end',
+  listConfig: ListActionAddOnValue<ItemValue>,
+) {
+  const { items, isItemDisabled, disableListWrap, disabledItemsFocusable, itemComparer } =
+    listConfig;
+
+  // TODO: make this configurable
   const defaultHighlightedIndex = -1;
+  const maxIndex = items.length - 1;
+
   const previouslyHighlightedIndex =
     previouslyHighlightedValue == null
       ? -1
@@ -65,9 +90,9 @@ function getNewHighlightedItem<ItemValue>(
 
   let nextIndexCandidate: number;
   let lookupDirection: 'next' | 'previous';
-  let wrapAround: boolean;
+  let wrapAround = !disableListWrap;
 
-  switch (diff) {
+  switch (offset) {
     case 'reset':
       if (defaultHighlightedIndex === -1) {
         return null;
@@ -91,11 +116,10 @@ function getNewHighlightedItem<ItemValue>(
       break;
 
     default: {
-      const newIndex = previouslyHighlightedIndex + diff;
-      wrapAround = !disableListWrap;
+      const newIndex = previouslyHighlightedIndex + offset;
 
       if (newIndex < 0) {
-        if ((!wrapAround && previouslyHighlightedIndex !== -1) || Math.abs(diff) > 1) {
+        if ((!wrapAround && previouslyHighlightedIndex !== -1) || Math.abs(offset) > 1) {
           nextIndexCandidate = 0;
           lookupDirection = 'next';
         } else {
@@ -103,7 +127,7 @@ function getNewHighlightedItem<ItemValue>(
           lookupDirection = 'previous';
         }
       } else if (newIndex > maxIndex) {
-        if (!wrapAround || Math.abs(diff) > 1) {
+        if (!wrapAround || Math.abs(offset) > 1) {
           nextIndexCandidate = maxIndex;
           lookupDirection = 'previous';
         } else {
@@ -112,7 +136,7 @@ function getNewHighlightedItem<ItemValue>(
         }
       } else {
         nextIndexCandidate = newIndex;
-        lookupDirection = diff >= 0 ? 'next' : 'previous';
+        lookupDirection = offset >= 0 ? 'next' : 'previous';
       }
     }
   }
@@ -121,7 +145,7 @@ function getNewHighlightedItem<ItemValue>(
     nextIndexCandidate,
     lookupDirection,
     items,
-    highlightDisabledItems,
+    disabledItemsFocusable,
     isItemDisabled,
     wrapAround,
   );
@@ -129,24 +153,16 @@ function getNewHighlightedItem<ItemValue>(
   return items[nextIndex] ?? null;
 }
 
-function moveHighlight<ItemValue>(
-  previouslyHighlightedValue: ItemValue | null,
-  diff: number | 'reset' | 'start' | 'end',
-  props: ListActionAddOnValue<ItemValue>,
-) {
-  const { items, isItemDisabled, disableListWrap, disabledItemsFocusable, itemComparer } = props;
-
-  return getNewHighlightedItem(
-    items,
-    previouslyHighlightedValue,
-    diff,
-    disabledItemsFocusable ?? false,
-    isItemDisabled ?? (() => false),
-    disableListWrap ?? false,
-    itemComparer ?? ((o1, o2) => o1 === o2),
-  );
-}
-
+/**
+ * Toggles the selection of an item.
+ *
+ * @param item Item to toggle.
+ * @param selectedValues Already selected items.
+ * @param selectionLimit The number of items that can be simultanously selected. If null, there is no limit.
+ * @param itemComparer A custom item comparer function.
+ *
+ * @returns The new array of selected items.
+ */
 function toggleSelection<ItemValue>(
   item: ItemValue,
   selectedValues: ItemValue[],
@@ -335,28 +351,13 @@ function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
   searchString: string,
   props: ListActionAddOnValue<ItemValue>,
 ): State {
-  const {
-    items,
-    isItemDisabled,
-    disableListWrap,
-    disabledItemsFocusable,
-    itemComparer,
-    itemStringifier,
-  } = props;
+  const { items, isItemDisabled, disabledItemsFocusable, itemStringifier } = props;
 
   const startWithCurrentItem = searchString.length > 1;
 
   let nextItem = startWithCurrentItem
     ? state.highlightedValue
-    : getNewHighlightedItem(
-        items,
-        state.highlightedValue,
-        1,
-        disabledItemsFocusable ?? false,
-        isItemDisabled ?? (() => false),
-        disableListWrap ?? false,
-        itemComparer,
-      );
+    : moveHighlight(state.highlightedValue, 1, props);
 
   // use `for` instead of `while` prevent infinite loop
   for (let index = 0; index < items.length; index += 1) {
@@ -376,15 +377,7 @@ function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
       };
     }
     // Move to the next element.
-    nextItem = getNewHighlightedItem(
-      items,
-      nextItem,
-      1,
-      disabledItemsFocusable ?? false,
-      isItemDisabled ?? (() => false),
-      disableListWrap ?? false,
-      itemComparer,
-    );
+    nextItem = moveHighlight(nextItem, 1, props);
   }
 
   // No item matches the text search criteria
@@ -421,7 +414,7 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
   };
 }
 
-export default function defaultListboxReducer<ItemValue, State extends ListState<ItemValue>>(
+export default function listReducer<ItemValue, State extends ListState<ItemValue>>(
   state: State,
   action: ListReducerAction<ItemValue, State> & ListActionAddOn<ItemValue>,
 ): State {
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 6b71442cf7b8e3..334fd951fff32a 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -10,7 +10,7 @@ import {
 } from './useList.types';
 import { ListActionTypes, ListAction } from './listActions.types';
 import { ListContextValue } from './ListContext';
-import defaultReducer from './defaultListboxReducer';
+import defaultReducer from './listReducer';
 import useListChangeNotifiers from './useListChangeNotifiers';
 import useControllableReducer from '../utils/useControllableReducer';
 import {
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 618d5a525d2f9f..c26981d90f4359 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -1,11 +1,6 @@
 import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
-import useList, {
-  defaultListboxReducer,
-  ListActionTypes,
-  ListActionAddOn,
-  ListAction,
-} from '../useList';
+import useList, { listReducer, ListActionTypes, ListActionAddOn, ListAction } from '../useList';
 import {
   MenuInternalState,
   UseMenuListboxSlotProps,
@@ -60,7 +55,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
         return state;
       }
 
-      const newState = defaultListboxReducer(state, action);
+      const newState = listReducer(state, action);
 
       // make sure an item is always highlighted
       if (newState.highlightedValue === null && action.props.current!.items.length > 0) {
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 64e32905ec48dc..7475501ee372b2 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -17,7 +17,7 @@ import {
   UseSelectResult,
 } from './useSelect.types';
 import useList, {
-  defaultListboxReducer,
+  listReducer,
   ListActionTypes,
   UseListParameters,
   ListAction,
@@ -159,7 +159,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
           break;
       }
 
-      const newState: SelectInternalState<TValue> = defaultListboxReducer(
+      const newState: SelectInternalState<TValue> = listReducer(
         state,
         action as ListAction<TValue, SelectInternalState<TValue>> & ListActionAddOn<TValue>,
       );
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index f67b9ee94a25a6..2da6e568419777 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -11,7 +11,7 @@ import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
 import useList, {
   ListActionTypes,
-  defaultListboxReducer,
+  listReducer,
   ListReducer,
   ListState,
   UseListParameters,
@@ -29,7 +29,6 @@ export const TabsListContext = React.createContext<TabsListContextValue | null>(
  *
  * - [useTabsList API](https://mui.com/base/react-tabs/hooks-api/#use-tabs-list)
  */
-
 function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue {
   const { ref: externalRef } = parameters;
 
@@ -70,7 +69,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
 
   const stateReducer: ListReducer<string | number, ListState<string | number>> = React.useCallback(
     (state, action) => {
-      const newState = defaultListboxReducer(state, action);
+      const newState = listReducer(state, action);
 
       if (action.type === ListActionTypes.itemsChange) {
         return {

From 2da76adaaa1e4e8a04f00c6bfe3becc3ca038dd9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 29 Mar 2023 15:20:01 +0200
Subject: [PATCH 11/49] API docs

---
 docs/pages/base/api/menu-unstyled.json        |  2 +-
 docs/pages/base/api/tab-unstyled.json         |  7 ++-
 docs/pages/base/api/tabs-unstyled.json        | 14 +-----
 docs/pages/base/api/use-button.json           |  7 +++
 docs/pages/base/api/use-menu-item.json        | 26 +++++------
 docs/pages/base/api/use-menu.json             | 14 ++++--
 docs/pages/base/api/use-option.json           |  5 ++
 docs/pages/base/api/use-tab.json              | 40 +++-------------
 docs/pages/base/api/use-tabs-list.json        | 46 ++++++++++++++-----
 docs/pages/base/api/use-tabs.json             | 19 +++++---
 docs/pages/joy-ui/api/tabs.json               | 14 +-----
 .../api-docs/menu-unstyled/menu-unstyled.json |  2 +-
 .../api-docs/use-button/use-button.json       |  1 +
 .../api-docs/use-menu-item/use-menu-item.json |  5 +-
 .../api-docs/use-tab/use-tab.json             | 15 +++---
 .../api-docs/use-tabs-list/use-tabs-list.json |  7 +--
 .../api-docs/use-tabs/use-tabs.json           |  2 +-
 .../src/MenuUnstyled/MenuUnstyled.tsx         |  6 ++-
 .../mui-base/src/TabUnstyled/TabUnstyled.tsx  |  2 +-
 .../src/TabsUnstyled/TabsUnstyled.tsx         |  4 +-
 packages/mui-base/src/useList/useListItem.ts  |  1 +
 .../mui-base/src/useMenu/MenuProvider.tsx     |  5 ++
 .../mui-base/src/useSelect/SelectProvider.tsx |  5 ++
 .../mui-base/src/useTabs/TabsProvider.tsx     |  2 +
 .../src/useTabsList/TabsListProvider.tsx      |  2 +
 packages/mui-joy/src/Tabs/Tabs.tsx            |  4 +-
 26 files changed, 141 insertions(+), 116 deletions(-)

diff --git a/docs/pages/base/api/menu-unstyled.json b/docs/pages/base/api/menu-unstyled.json
index b51dcf637d4d1f..757a82d53fc888 100644
--- a/docs/pages/base/api/menu-unstyled.json
+++ b/docs/pages/base/api/menu-unstyled.json
@@ -9,7 +9,7 @@
     },
     "component": { "type": { "name": "elementType" } },
     "keepMounted": { "type": { "name": "bool" }, "default": "false" },
-    "onClose": { "type": { "name": "func" } },
+    "onOpenChange": { "type": { "name": "func" } },
     "open": { "type": { "name": "bool" }, "default": "false" },
     "slotProps": {
       "type": {
diff --git a/docs/pages/base/api/tab-unstyled.json b/docs/pages/base/api/tab-unstyled.json
index 4faa9060244389..38caa81d44ef05 100644
--- a/docs/pages/base/api/tab-unstyled.json
+++ b/docs/pages/base/api/tab-unstyled.json
@@ -1,5 +1,9 @@
 {
   "props": {
+    "value": {
+      "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
+      "required": true
+    },
     "action": {
       "type": {
         "name": "union",
@@ -16,8 +20,7 @@
     "slots": {
       "type": { "name": "shape", "description": "{ root?: elementType }" },
       "default": "{}"
-    },
-    "value": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } }
+    }
   },
   "name": "TabUnstyled",
   "styles": { "classes": [], "globalClasses": {}, "name": null },
diff --git a/docs/pages/base/api/tabs-unstyled.json b/docs/pages/base/api/tabs-unstyled.json
index df2e6f65e1128d..629372a76b20e9 100644
--- a/docs/pages/base/api/tabs-unstyled.json
+++ b/docs/pages/base/api/tabs-unstyled.json
@@ -2,12 +2,7 @@
   "props": {
     "children": { "type": { "name": "node" } },
     "component": { "type": { "name": "elementType" } },
-    "defaultValue": {
-      "type": {
-        "name": "union",
-        "description": "false<br>&#124;&nbsp;number<br>&#124;&nbsp;string"
-      }
-    },
+    "defaultValue": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } },
     "direction": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
@@ -26,12 +21,7 @@
       "type": { "name": "shape", "description": "{ root?: elementType }" },
       "default": "{}"
     },
-    "value": {
-      "type": {
-        "name": "union",
-        "description": "false<br>&#124;&nbsp;number<br>&#124;&nbsp;string"
-      }
-    }
+    "value": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } }
   },
   "name": "TabsUnstyled",
   "styles": { "classes": [], "globalClasses": {}, "name": null },
diff --git a/docs/pages/base/api/use-button.json b/docs/pages/base/api/use-button.json
index 00b73df07d8a88..cfd717d3b3e77d 100644
--- a/docs/pages/base/api/use-button.json
+++ b/docs/pages/base/api/use-button.json
@@ -48,6 +48,13 @@
       },
       "required": true
     },
+    "ref": {
+      "type": {
+        "name": "((instance: unknown) =&gt; void) | null",
+        "description": "((instance: unknown) =&gt; void) | null"
+      },
+      "required": true
+    },
     "setFocusVisible": {
       "type": {
         "name": "React.Dispatch&lt;React.SetStateAction&lt;boolean&gt;&gt;",
diff --git a/docs/pages/base/api/use-menu-item.json b/docs/pages/base/api/use-menu-item.json
index 459097b94b117b..3b9bdb346daeca 100644
--- a/docs/pages/base/api/use-menu-item.json
+++ b/docs/pages/base/api/use-menu-item.json
@@ -5,6 +5,7 @@
       "required": true
     },
     "disabled": { "type": { "name": "boolean", "description": "boolean" } },
+    "id": { "type": { "name": "string", "description": "string" } },
     "label": { "type": { "name": "string", "description": "string" } },
     "onClick": {
       "type": {
@@ -14,16 +15,8 @@
     }
   },
   "returnValue": {
-    "disabled": {
-      "type": { "name": "boolean", "description": "boolean" },
-      "default": "false",
-      "required": true
-    },
-    "focusVisible": {
-      "type": { "name": "boolean", "description": "boolean" },
-      "default": "false",
-      "required": true
-    },
+    "disabled": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "focusVisible": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "getRootProps": {
       "type": {
         "name": "&lt;TOther extends EventHandlers = {}&gt;(otherHandlers?: TOther) =&gt; UseMenuItemRootSlotProps&lt;TOther&gt;",
@@ -31,11 +24,16 @@
       },
       "required": true
     },
-    "highlighted": {
-      "type": { "name": "boolean", "description": "boolean" },
-      "default": "false",
+    "highlighted": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "index": { "type": { "name": "number", "description": "number" }, "required": true },
+    "ref": {
+      "type": {
+        "name": "((instance: unknown) =&gt; void) | null",
+        "description": "((instance: unknown) =&gt; void) | null"
+      },
       "required": true
-    }
+    },
+    "totalItemCount": { "type": { "name": "number", "description": "number" }, "required": true }
   },
   "name": "useMenuItem",
   "filename": "/packages/mui-base/src/useMenuItem/useMenuItem.ts",
diff --git a/docs/pages/base/api/use-menu.json b/docs/pages/base/api/use-menu.json
index f67a9cbc9f6a86..703a5b5479945b 100644
--- a/docs/pages/base/api/use-menu.json
+++ b/docs/pages/base/api/use-menu.json
@@ -1,15 +1,18 @@
 {
   "parameters": {
+    "defaultOpen": { "type": { "name": "boolean", "description": "boolean" } },
     "listboxId": { "type": { "name": "string", "description": "string" } },
     "listboxRef": {
       "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" }
     },
-    "onClose": { "type": { "name": "() =&gt; void", "description": "() =&gt; void" } },
+    "onOpenChange": {
+      "type": { "name": "(open: boolean) =&gt; void", "description": "(open: boolean) =&gt; void" }
+    },
     "open": { "type": { "name": "boolean", "description": "boolean" } }
   },
   "returnValue": {
     "contextValue": {
-      "type": { "name": "MenuUnstyledContextType", "description": "MenuUnstyledContextType" },
+      "type": { "name": "MenuProviderValue", "description": "MenuProviderValue" },
       "required": true
     },
     "getListboxProps": {
@@ -33,11 +36,12 @@
     },
     "menuItems": {
       "type": {
-        "name": "Record&lt;string, MenuItemMetadata&gt;",
-        "description": "Record&lt;string, MenuItemMetadata&gt;"
+        "name": "Map&lt;string, MenuItemMetadata&gt;",
+        "description": "Map&lt;string, MenuItemMetadata&gt;"
       },
       "required": true
-    }
+    },
+    "open": { "type": { "name": "boolean", "description": "boolean" }, "required": true }
   },
   "name": "useMenu",
   "filename": "/packages/mui-base/src/useMenu/useMenu.ts",
diff --git a/docs/pages/base/api/use-option.json b/docs/pages/base/api/use-option.json
index 091898c40a09c7..a9c89561e50f0e 100644
--- a/docs/pages/base/api/use-option.json
+++ b/docs/pages/base/api/use-option.json
@@ -1,7 +1,12 @@
 {
   "parameters": {
     "disabled": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "label": {
+      "type": { "name": "string | React.ReactNode", "description": "string | React.ReactNode" },
+      "required": true
+    },
     "value": { "type": { "name": "Value", "description": "Value" }, "required": true },
+    "id": { "type": { "name": "string", "description": "string" } },
     "optionRef": {
       "type": {
         "name": "React.Ref&lt;HTMLElement&gt;",
diff --git a/docs/pages/base/api/use-tab.json b/docs/pages/base/api/use-tab.json
index f732cb3626c25b..f1333c1b2f1ef0 100644
--- a/docs/pages/base/api/use-tab.json
+++ b/docs/pages/base/api/use-tab.json
@@ -1,36 +1,14 @@
 {
   "parameters": {
-    "ref": {
-      "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" },
+    "value": {
+      "type": { "name": "number | string", "description": "number | string" },
       "required": true
     },
     "disabled": { "type": { "name": "boolean", "description": "boolean" } },
-    "onChange": {
-      "type": {
-        "name": "(event: React.SyntheticEvent, value: number | string) =&gt; void",
-        "description": "(event: React.SyntheticEvent, value: number | string) =&gt; void"
-      }
-    },
-    "onClick": {
-      "type": { "name": "React.MouseEventHandler", "description": "React.MouseEventHandler" }
-    },
-    "onFocus": {
-      "type": { "name": "React.FocusEventHandler", "description": "React.FocusEventHandler" }
-    },
-    "value": { "type": { "name": "number | string", "description": "number | string" } }
+    "ref": { "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" } }
   },
   "returnValue": {
-    "active": {
-      "type": { "name": "boolean", "description": "boolean" },
-      "default": "false",
-      "required": true
-    },
-    "disabled": {
-      "type": { "name": "boolean", "description": "boolean" },
-      "default": "false",
-      "required": true
-    },
-    "focusVisible": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "active": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "getRootProps": {
       "type": {
         "name": "&lt;TOther extends Record&lt;string, any&gt; = {}&gt;(externalProps?: TOther) =&gt; UseTabRootSlotProps&lt;TOther&gt;",
@@ -38,14 +16,10 @@
       },
       "required": true
     },
+    "highlighted": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "index": { "type": { "name": "number", "description": "number" }, "required": true },
     "selected": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
-    "setFocusVisible": {
-      "type": {
-        "name": "React.Dispatch&lt;React.SetStateAction&lt;boolean&gt;&gt;",
-        "description": "React.Dispatch&lt;React.SetStateAction&lt;boolean&gt;&gt;"
-      },
-      "required": true
-    }
+    "totalTabsCount": { "type": { "name": "number", "description": "number" }, "required": true }
   },
   "name": "useTab",
   "filename": "/packages/mui-base/src/useTab/useTab.ts",
diff --git a/docs/pages/base/api/use-tabs-list.json b/docs/pages/base/api/use-tabs-list.json
index 847034026445a5..b8e4327a6af97f 100644
--- a/docs/pages/base/api/use-tabs-list.json
+++ b/docs/pages/base/api/use-tabs-list.json
@@ -4,11 +4,36 @@
       "type": { "name": "React.Ref&lt;unknown&gt;", "description": "React.Ref&lt;unknown&gt;" },
       "required": true
     },
-    "aria-label": { "type": { "name": "string", "description": "string" } },
-    "aria-labelledby": { "type": { "name": "string", "description": "string" } },
-    "children": { "type": { "name": "React.ReactNode", "description": "React.ReactNode" } }
+    "defaultValue": {
+      "type": { "name": "string | number | null", "description": "string | number | null" }
+    },
+    "direction": {
+      "type": {
+        "name": "&#39;ltr&#39; | &#39;rtl&#39;",
+        "description": "&#39;ltr&#39; | &#39;rtl&#39;"
+      }
+    },
+    "onChange": {
+      "type": {
+        "name": "(event: React.SyntheticEvent | null, value: string | number | null) =&gt; void",
+        "description": "(event: React.SyntheticEvent | null, value: string | number | null) =&gt; void"
+      }
+    },
+    "orientation": {
+      "type": {
+        "name": "&#39;horizontal&#39; | &#39;vertical&#39;",
+        "description": "&#39;horizontal&#39; | &#39;vertical&#39;"
+      }
+    },
+    "value": {
+      "type": { "name": "string | number | null", "description": "string | number | null" }
+    }
   },
   "returnValue": {
+    "contextValue": {
+      "type": { "name": "TabsListProviderValue", "description": "TabsListProviderValue" },
+      "required": true
+    },
     "getRootProps": {
       "type": {
         "name": "&lt;TOther extends Record&lt;string, any&gt; = {}&gt;(externalProps?: TOther) =&gt; UseTabsListRootSlotProps&lt;TOther&gt;",
@@ -16,6 +41,10 @@
       },
       "required": true
     },
+    "highlightedValue": {
+      "type": { "name": "string | number | null", "description": "string | number | null" },
+      "required": true
+    },
     "isRtl": {
       "type": { "name": "boolean", "description": "boolean" },
       "default": "false",
@@ -29,15 +58,8 @@
       "default": "'horizontal'",
       "required": true
     },
-    "processChildren": {
-      "type": {
-        "name": "() =&gt; React.ReactElement&lt;any, string | React.JSXElementConstructor&lt;any&gt;&gt;[] | null | undefined",
-        "description": "() =&gt; React.ReactElement&lt;any, string | React.JSXElementConstructor&lt;any&gt;&gt;[] | null | undefined"
-      },
-      "required": true
-    },
-    "value": {
-      "type": { "name": "string | number | false", "description": "string | number | false" },
+    "selectedValue": {
+      "type": { "name": "string | number | null", "description": "string | number | null" },
       "required": true
     }
   },
diff --git a/docs/pages/base/api/use-tabs.json b/docs/pages/base/api/use-tabs.json
index 979d10a730c013..221b1a11ea62b4 100644
--- a/docs/pages/base/api/use-tabs.json
+++ b/docs/pages/base/api/use-tabs.json
@@ -1,7 +1,7 @@
 {
   "parameters": {
     "defaultValue": {
-      "type": { "name": "string | number | false", "description": "string | number | false" }
+      "type": { "name": "string | number | null", "description": "string | number | null" }
     },
     "direction": {
       "type": {
@@ -12,8 +12,8 @@
     },
     "onChange": {
       "type": {
-        "name": "(event: React.SyntheticEvent, value: number | string | boolean) =&gt; void",
-        "description": "(event: React.SyntheticEvent, value: number | string | boolean) =&gt; void"
+        "name": "(event: React.SyntheticEvent | null, value: number | string | null) =&gt; void",
+        "description": "(event: React.SyntheticEvent | null, value: number | string | null) =&gt; void"
       }
     },
     "orientation": {
@@ -25,12 +25,19 @@
     },
     "selectionFollowsFocus": { "type": { "name": "boolean", "description": "boolean" } },
     "value": {
-      "type": { "name": "string | number | false", "description": "string | number | false" }
+      "type": { "name": "string | number | null", "description": "string | number | null" }
     }
   },
   "returnValue": {
-    "tabsContextValue": {
-      "type": { "name": "TabsContextValue", "description": "TabsContextValue" },
+    "contextValue": {
+      "type": { "name": "TabsProviderValue", "description": "TabsProviderValue" },
+      "required": true
+    },
+    "tabPanels": {
+      "type": {
+        "name": "Map&lt;string | number, string&gt;",
+        "description": "Map&lt;string | number, string&gt;"
+      },
       "required": true
     }
   },
diff --git a/docs/pages/joy-ui/api/tabs.json b/docs/pages/joy-ui/api/tabs.json
index 78452a7aa90a21..10e6f5257a1030 100644
--- a/docs/pages/joy-ui/api/tabs.json
+++ b/docs/pages/joy-ui/api/tabs.json
@@ -9,12 +9,7 @@
       "default": "'neutral'"
     },
     "component": { "type": { "name": "elementType" } },
-    "defaultValue": {
-      "type": {
-        "name": "union",
-        "description": "false<br>&#124;&nbsp;number<br>&#124;&nbsp;string"
-      }
-    },
+    "defaultValue": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } },
     "direction": {
       "type": { "name": "enum", "description": "'ltr'<br>&#124;&nbsp;'rtl'" },
       "default": "'ltr'"
@@ -38,12 +33,7 @@
         "description": "Array&lt;func<br>&#124;&nbsp;object<br>&#124;&nbsp;bool&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object"
       }
     },
-    "value": {
-      "type": {
-        "name": "union",
-        "description": "false<br>&#124;&nbsp;number<br>&#124;&nbsp;string"
-      }
-    },
+    "value": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } },
     "variant": {
       "type": {
         "name": "union",
diff --git a/docs/translations/api-docs/menu-unstyled/menu-unstyled.json b/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
index 7d2b60bc01e1d7..2ca38098db4181 100644
--- a/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
+++ b/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
@@ -5,7 +5,7 @@
     "anchorEl": "An HTML element, <a href=\"https://popper.js.org/docs/v2/virtual-elements/\">virtualElement</a>, or a function that returns either. It&#39;s used to set the position of the popper.",
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
     "keepMounted": "Always keep the menu in the DOM. This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.",
-    "onClose": "Triggered when focus leaves the menu and the menu should close.",
+    "onOpenChange": "Triggered when focus leaves the menu and the menu should close.",
     "open": "Controls whether the menu is displayed.",
     "slotProps": "The props used for each slot inside the Menu.",
     "slots": "The components used for each slot inside the Menu. Either a string to use a HTML element or a component. See <a href=\"#slots\">Slots API</a> below for more details."
diff --git a/docs/translations/api-docs/use-button/use-button.json b/docs/translations/api-docs/use-button/use-button.json
index a1fefeab7fc5a6..15688c68bc0ed6 100644
--- a/docs/translations/api-docs/use-button/use-button.json
+++ b/docs/translations/api-docs/use-button/use-button.json
@@ -10,6 +10,7 @@
     "disabled": "If <code>true</code>, the component is disabled.",
     "focusVisible": "If <code>true</code>, the component is being focused using keyboard.",
     "getRootProps": "Resolver for the root slot's props.",
+    "ref": "A ref to the component's root DOM element.",
     "setFocusVisible": "Callback for setting the <code>focusVisible</code> param."
   }
 }
diff --git a/docs/translations/api-docs/use-menu-item/use-menu-item.json b/docs/translations/api-docs/use-menu-item/use-menu-item.json
index 2c2401f077ace3..5c2971b849e460 100644
--- a/docs/translations/api-docs/use-menu-item/use-menu-item.json
+++ b/docs/translations/api-docs/use-menu-item/use-menu-item.json
@@ -5,6 +5,9 @@
     "disabled": "If <code>true</code>, the component is disabled.",
     "focusVisible": "If <code>true</code>, the component is being focused using keyboard.",
     "getRootProps": "Resolver for the root slot's props.",
-    "highlighted": "If <code>true</code>, the component is being highlighted."
+    "highlighted": "If <code>true</code>, the component is being highlighted.",
+    "index": "0-based index of the item in the menu.",
+    "ref": "The ref to the component's root DOM element.",
+    "totalItemCount": "Total number of items in the menu."
   }
 }
diff --git a/docs/translations/api-docs/use-tab/use-tab.json b/docs/translations/api-docs/use-tab/use-tab.json
index eb17fa2ef09423..73324af032c9f5 100644
--- a/docs/translations/api-docs/use-tab/use-tab.json
+++ b/docs/translations/api-docs/use-tab/use-tab.json
@@ -1,15 +1,16 @@
 {
   "hookDescription": "",
   "parametersDescriptions": {
-    "onChange": "Callback invoked when new value is being set.",
-    "value": "You can provide your own value. Otherwise, we fall back to the child position index."
+    "disabled": "If <code>true</code>, the tab will be disabled.",
+    "ref": "Ref to the DOM element associated with the tab.",
+    "value": "The value of the tab.\nIt's used to associate the tab with a tab panel(s) with the same value."
   },
   "returnValueDescriptions": {
-    "active": "If <code>true</code>, the component will be active.",
-    "disabled": "If <code>true</code>, the component will be disabled.",
-    "focusVisible": "If <code>true</code>, the tab's focus will be visible.",
+    "active": "If <code>true</code>, the tab is active (as in </code>:active</code> pseudo-class; in other words, pressed).",
     "getRootProps": "Resolver for the root slot's props.",
-    "selected": "If <code>true</code>, the tab will be selected.",
-    "setFocusVisible": "Callback for setting the <code>focusVisible</code> param."
+    "highlighted": "If <code>true</code>, the tab is highlighted.",
+    "index": "0-based index of the tab in the list of tabs.",
+    "selected": "If <code>true</code>, the tab is selected.",
+    "totalTabsCount": "Total number of tabs in the nearest parent TabsList.\nThis can be used to determine if the tab is the last one to style it accordingly."
   }
 }
diff --git a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
index a63696dd8c378d..c45ecc6214a8dd 100644
--- a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
+++ b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
@@ -1,11 +1,12 @@
 {
   "hookDescription": "",
-  "parametersDescriptions": { "children": "The content of the component." },
+  "parametersDescriptions": {},
   "returnValueDescriptions": {
+    "contextValue": "The value to be passed to the TabListProvider above all the tabs.",
     "getRootProps": "Resolver for the root slot's props.",
+    "highlightedValue": "The value of the currently highlighted <code>Tab</code>.",
     "isRtl": "If <code>true</code>, it will indicate that the text's direction in right-to-left.",
     "orientation": "The component orientation (layout flow direction).",
-    "processChildren": "Callback for processing the children of the tabs list. It adds the necessary attributes for correct a11y and navigation.",
-    "value": "The value of the currently selected <code>Tab</code>."
+    "selectedValue": "The value of the currently selected <code>Tab</code>."
   }
 }
diff --git a/docs/translations/api-docs/use-tabs/use-tabs.json b/docs/translations/api-docs/use-tabs/use-tabs.json
index 5fc66c64729d2d..b81de1149c3253 100644
--- a/docs/translations/api-docs/use-tabs/use-tabs.json
+++ b/docs/translations/api-docs/use-tabs/use-tabs.json
@@ -9,6 +9,6 @@
     "value": "The value of the currently selected <code>Tab</code>.\nIf you don't want any selected <code>Tab</code>, you can set this prop to <code>false</code>."
   },
   "returnValueDescriptions": {
-    "tabsContextValue": "Returns the values to be passed to the tabs context provider."
+    "contextValue": "Returns the values to be passed to the tabs provider."
   }
 }
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
index c9005c48bfdaad..946eeb77dbdd2e 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
@@ -139,6 +139,10 @@ MenuUnstyled.propTypes /* remove-proptypes */ = {
    * Either a string to use a HTML element or a component.
    */
   component: PropTypes.elementType,
+  /**
+   * @ignore
+   */
+  defaultOpen: PropTypes.bool,
   /**
    * Always keep the menu in the DOM.
    * This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.
@@ -153,7 +157,7 @@ MenuUnstyled.propTypes /* remove-proptypes */ = {
   /**
    * Triggered when focus leaves the menu and the menu should close.
    */
-  onClose: PropTypes.func,
+  onOpenChange: PropTypes.func,
   /**
    * Controls whether the menu is displayed.
    * @default false
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
index cf44579186671c..3070308a86d874 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
@@ -142,7 +142,7 @@ TabUnstyled.propTypes /* remove-proptypes */ = {
   /**
    * You can provide your own value. Otherwise, we fall back to the child position index.
    */
-  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]).isRequired,
 } as any;
 
 export default TabUnstyled;
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
index 7888518e34cdd7..b8b5ec71e8c599 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
@@ -97,7 +97,7 @@ TabsUnstyled.propTypes /* remove-proptypes */ = {
   /**
    * The default value. Use when the component is not controlled.
    */
-  defaultValue: PropTypes.oneOfType([PropTypes.oneOf([false]), PropTypes.number, PropTypes.string]),
+  defaultValue: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   /**
    * The direction of the text.
    * @default 'ltr'
@@ -136,7 +136,7 @@ TabsUnstyled.propTypes /* remove-proptypes */ = {
    * The value of the currently selected `Tab`.
    * If you don't want any selected `Tab`, you can set this prop to `false`.
    */
-  value: PropTypes.oneOfType([PropTypes.oneOf([false]), PropTypes.number, PropTypes.string]),
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
 } as any;
 
 export default TabsUnstyled;
diff --git a/packages/mui-base/src/useList/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
index 318dc33b43ffe4..f55ed70b2e3f57 100644
--- a/packages/mui-base/src/useList/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -15,6 +15,7 @@ import { ListContext } from './ListContext';
  * handles the item's mouse events.
  *
  * @template ItemValue The type of the item's value. This should be consistent with the type of useList's `items` parameter.
+ * @ignore - internal hook.
  */
 export default function useListItem<ItemValue>(
   parameters: UseListItemParameters<ItemValue>,
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
index fd01974dcda40d..94342b68fab704 100644
--- a/packages/mui-base/src/useMenu/MenuProvider.tsx
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -12,6 +12,11 @@ export interface MenuProviderProps {
   children: React.ReactNode;
 }
 
+/**
+ * Sets up the contexts for the underlying MenuItem components.
+ *
+ * @ignore - do not document.
+ */
 export default function MenuProvider(props: MenuProviderProps) {
   const { value, children } = props;
 
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
index d07afe33173c89..6323868df7965d 100644
--- a/packages/mui-base/src/useSelect/SelectProvider.tsx
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -12,6 +12,11 @@ export interface SelectProviderProps<Value> {
   children: React.ReactNode;
 }
 
+/**
+ * Sets up the contexts for the underlying Option components.
+ *
+ * @ignore - do not document.
+ */
 export default function SelectProvider<Value>(props: SelectProviderProps<Value>) {
   const { value, children } = props;
 
diff --git a/packages/mui-base/src/useTabs/TabsProvider.tsx b/packages/mui-base/src/useTabs/TabsProvider.tsx
index d2abc1c11ba742..06b58495ce1b45 100644
--- a/packages/mui-base/src/useTabs/TabsProvider.tsx
+++ b/packages/mui-base/src/useTabs/TabsProvider.tsx
@@ -12,6 +12,8 @@ export interface TabsProviderProps {
 
 /**
  * Sets up the contexts for the underlying Tab and TabPanel components.
+ *
+ * @ignore - do not document.
  */
 export default function TabsProvider(props: TabsProviderProps) {
   const { value: valueProp, children } = props;
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index b5818a2cf0c771..a19202739be30d 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -14,6 +14,8 @@ export interface TabsListProviderProps {
 
 /**
  * Sets up the contexts for the underlying Tab components.
+ *
+ * @ignore - do not document.
  */
 export default function TabsListProvider(props: TabsListProviderProps) {
   const { value, children } = props;
diff --git a/packages/mui-joy/src/Tabs/Tabs.tsx b/packages/mui-joy/src/Tabs/Tabs.tsx
index 393bec23436d6d..5d39deba4cbaeb 100644
--- a/packages/mui-joy/src/Tabs/Tabs.tsx
+++ b/packages/mui-joy/src/Tabs/Tabs.tsx
@@ -142,7 +142,7 @@ Tabs.propTypes /* remove-proptypes */ = {
   /**
    * The default value. Use when the component is not controlled.
    */
-  defaultValue: PropTypes.oneOfType([PropTypes.oneOf([false]), PropTypes.number, PropTypes.string]),
+  defaultValue: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   /**
    * The direction of the text.
    * @default 'ltr'
@@ -182,7 +182,7 @@ Tabs.propTypes /* remove-proptypes */ = {
    * The value of the currently selected `Tab`.
    * If you don't want any selected `Tab`, you can set this prop to `false`.
    */
-  value: PropTypes.oneOfType([PropTypes.oneOf([false]), PropTypes.number, PropTypes.string]),
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   /**
    * The [global variant](https://mui.com/joy-ui/main-features/global-variants/) to use.
    * @default 'plain'

From 34fa5ac54b3d44be2b79497708289e06cd726cf5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 29 Mar 2023 20:56:56 +0200
Subject: [PATCH 12/49] Do not require compound subcomponents to have a defined
 value

---
 .../MenuItemUnstyled.test.tsx                 |   3 +-
 .../OptionUnstyled/OptionUnstyled.test.tsx    |   6 +-
 .../src/TabUnstyled/TabUnstyled.test.tsx      |   3 +-
 .../mui-base/src/TabUnstyled/TabUnstyled.tsx  |   2 +-
 .../src/TabUnstyled/TabUnstyled.types.ts      |   2 +-
 .../mui-base/src/useMenu/MenuProvider.tsx     |   4 +-
 .../mui-base/src/useMenuItem/useMenuItem.ts   |   2 +-
 packages/mui-base/src/useOption/useOption.ts  |   2 +-
 .../mui-base/src/useSelect/SelectProvider.tsx |   4 +-
 packages/mui-base/src/useTab/useTab.ts        |  24 ++--
 packages/mui-base/src/useTab/useTab.types.ts  |   2 +-
 .../mui-base/src/useTabs/TabsProvider.tsx     |   4 +-
 .../src/useTabsList/TabsListProvider.tsx      |   4 +-
 .../mui-base/src/utils/useCompound.test.tsx   |  39 ++++-
 packages/mui-base/src/utils/useCompound.ts    | 134 ++++++++++--------
 .../mui-base/src/utils/useCompoundItem.ts     |  63 ++++++++
 .../mui-joy/src/MenuItem/MenuItem.test.js     |   1 +
 17 files changed, 203 insertions(+), 96 deletions(-)
 create mode 100644 packages/mui-base/src/utils/useCompoundItem.ts

diff --git a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
index 29083c5f96f074..1e9d1f3c99f59f 100644
--- a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
+++ b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
@@ -18,10 +18,9 @@ const testContext = {
   getItemState: dummyGetItemState,
   open: false,
   registerHighlightChangeHandler: () => () => {},
-  registerItem: () => {},
+  registerItem: () => ({ id: '', unregister: () => {} }),
   registerSelectionChangeHandler: () => () => {},
   totalSubitemCount: 0,
-  unregisterItem: () => {},
 };
 
 describe('<MenuItemUnstyled />', () => {
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
index 50520ec8d3df43..0b69f45dd01125 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
@@ -25,10 +25,9 @@ describe('<OptionUnstyled />', () => {
             getItemIndex: () => 0,
             getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
-            registerItem: () => () => {},
+            registerItem: () => ({ id: 0, unregister: () => {} }),
             registerSelectionChangeHandler: () => () => {},
             totalSubitemCount: 0,
-            unregisterItem: () => () => {},
           }}
         >
           {node}
@@ -43,10 +42,9 @@ describe('<OptionUnstyled />', () => {
             getItemIndex: () => 0,
             getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
-            registerItem: () => () => {},
+            registerItem: () => ({ id: 0, unregister: () => {} }),
             registerSelectionChangeHandler: () => () => {},
             totalSubitemCount: 0,
-            unregisterItem: () => () => {},
           }}
         >
           {node}
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
index c6c6b2852610d6..884ae8f1729a2d 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
@@ -10,8 +10,7 @@ describe('<TabUnstyled />', () => {
 
   const testTabsListContext: TabsListProviderValue = {
     dispatch: () => {},
-    registerItem: () => {},
-    unregisterItem: () => {},
+    registerItem: () => ({ id: 0, unregister: () => {} }),
     getItemIndex: () => 0,
     totalSubitemCount: 1,
     getItemState() {
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
index 3070308a86d874..cf44579186671c 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.tsx
@@ -142,7 +142,7 @@ TabUnstyled.propTypes /* remove-proptypes */ = {
   /**
    * You can provide your own value. Otherwise, we fall back to the child position index.
    */
-  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]).isRequired,
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
 } as any;
 
 export default TabUnstyled;
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts b/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
index 51b4f3f85a501f..52b22d3dcbfe60 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.types.ts
@@ -11,7 +11,7 @@ export interface TabUnstyledOwnProps
   /**
    * You can provide your own value. Otherwise, we fall back to the child position index.
    */
-  value: number | string;
+  value?: number | string;
   /**
    * Callback invoked when new value is being set.
    */
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
index 94342b68fab704..1ba94b905474af 100644
--- a/packages/mui-base/src/useMenu/MenuProvider.tsx
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -27,7 +27,6 @@ export default function MenuProvider(props: MenuProviderProps) {
     registerHighlightChangeHandler,
     registerSelectionChangeHandler,
     registerItem,
-    unregisterItem,
     totalSubitemCount,
   } = value;
 
@@ -54,9 +53,8 @@ export default function MenuProvider(props: MenuProviderProps) {
         getItemIndex,
         registerItem,
         totalSubitemCount,
-        unregisterItem,
       }),
-      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+      [registerItem, getItemIndex, totalSubitemCount],
     );
 
   return (
diff --git a/packages/mui-base/src/useMenuItem/useMenuItem.ts b/packages/mui-base/src/useMenuItem/useMenuItem.ts
index 18aa68e278ea8c..f9addc2837ebdb 100644
--- a/packages/mui-base/src/useMenuItem/useMenuItem.ts
+++ b/packages/mui-base/src/useMenuItem/useMenuItem.ts
@@ -9,7 +9,7 @@ import {
   UseMenuItemRootSlotProps,
 } from './useMenuItem.types';
 import { useListItem } from '../useList';
-import { useCompoundItem } from '../utils/useCompound';
+import { useCompoundItem } from '../utils/useCompoundItem';
 
 /**
  *
diff --git a/packages/mui-base/src/useOption/useOption.ts b/packages/mui-base/src/useOption/useOption.ts
index b4b4933e288141..22740cccf50051 100644
--- a/packages/mui-base/src/useOption/useOption.ts
+++ b/packages/mui-base/src/useOption/useOption.ts
@@ -3,7 +3,7 @@ import { unstable_useForkRef as useForkRef, unstable_useId as useId } from '@mui
 import { SelectOption, UseOptionParameters, UseOptionReturnValue } from './useOption.types';
 import { EventHandlers } from '../utils';
 import { useListItem } from '../useList';
-import { useCompoundItem } from '../utils/useCompound';
+import { useCompoundItem } from '../utils/useCompoundItem';
 
 /**
  *
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
index 6323868df7965d..8fa41a561df2b0 100644
--- a/packages/mui-base/src/useSelect/SelectProvider.tsx
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -27,7 +27,6 @@ export default function SelectProvider<Value>(props: SelectProviderProps<Value>)
     registerHighlightChangeHandler,
     registerSelectionChangeHandler,
     registerItem,
-    unregisterItem,
     totalSubitemCount,
   } = value;
 
@@ -56,9 +55,8 @@ export default function SelectProvider<Value>(props: SelectProviderProps<Value>)
       getItemIndex,
       registerItem,
       totalSubitemCount,
-      unregisterItem,
     }),
-    [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+    [registerItem, getItemIndex, totalSubitemCount],
   );
 
   return (
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index 00efac9a22a4fd..9ea28cef1df883 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -3,10 +3,15 @@ import { unstable_useId as useId, unstable_useForkRef as useForkRef } from '@mui
 import { useTabContext } from '../TabsUnstyled';
 import { UseTabParameters, UseTabReturnValue, UseTabRootSlotProps } from './useTab.types';
 import { EventHandlers } from '../utils';
-import { useCompoundItem } from '../utils/useCompound';
+import { useCompoundItem } from '../utils/useCompoundItem';
 import { useListItem } from '../useList';
 import useButton from '../useButton';
 import { TabMetadata } from '../useTabs';
+
+function tabValueGenerator(otherTabValues: Set<string | number>) {
+  return otherTabValues.size;
+}
+
 /**
  *
  * Demos:
@@ -18,12 +23,20 @@ import { TabMetadata } from '../useTabs';
  * - [useTab API](https://mui.com/base/react-tabs/hooks-api/#use-tab)
  */
 function useTab(parameters: UseTabParameters): UseTabReturnValue {
-  const { value, ref: externalRef, disabled = false } = parameters;
+  const { value: valueParam, ref: externalRef, disabled = false } = parameters;
 
   const tabRef = React.useRef<HTMLElement>(null);
 
   const { value: selectedValue, idPrefix = '', selectionFollowsFocus } = useTabContext();
 
+  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef }), [disabled, tabRef]);
+
+  const {
+    id: value,
+    index,
+    totalItemCount: totalTabsCount,
+  } = useCompoundItem<string | number, TabMetadata>(valueParam, tabMetadata, tabValueGenerator);
+
   const {
     getRootProps: getTabProps,
     ref: listItemRefHandler,
@@ -47,13 +60,6 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
 
   const tabId = idPrefix + useId();
 
-  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef }), [disabled, tabRef]);
-
-  const { index, totalItemCount: totalTabsCount } = useCompoundItem<string | number, TabMetadata>(
-    value,
-    tabMetadata,
-  );
-
   const getRootProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabRootSlotProps<TOther> => {
diff --git a/packages/mui-base/src/useTab/useTab.types.ts b/packages/mui-base/src/useTab/useTab.types.ts
index 6e0865add74fb0..0d4a8d4250fb85 100644
--- a/packages/mui-base/src/useTab/useTab.types.ts
+++ b/packages/mui-base/src/useTab/useTab.types.ts
@@ -6,7 +6,7 @@ export interface UseTabParameters {
    * The value of the tab.
    * It's used to associate the tab with a tab panel(s) with the same value.
    */
-  value: number | string;
+  value?: number | string;
   /**
    * If `true`, the tab will be disabled.
    */
diff --git a/packages/mui-base/src/useTabs/TabsProvider.tsx b/packages/mui-base/src/useTabs/TabsProvider.tsx
index 06b58495ce1b45..e61686266c1729 100644
--- a/packages/mui-base/src/useTabs/TabsProvider.tsx
+++ b/packages/mui-base/src/useTabs/TabsProvider.tsx
@@ -26,7 +26,6 @@ export default function TabsProvider(props: TabsProviderProps) {
     registerItem,
     selectionFollowsFocus,
     totalSubitemCount,
-    unregisterItem,
     value,
   } = valueProp;
 
@@ -36,9 +35,8 @@ export default function TabsProvider(props: TabsProviderProps) {
         getItemIndex,
         registerItem,
         totalSubitemCount,
-        unregisterItem,
       }),
-      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+      [registerItem, getItemIndex, totalSubitemCount],
     );
 
   const tabsContextValue: TabsContextValue = React.useMemo(
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index a19202739be30d..29e0e49beafcca 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -26,7 +26,6 @@ export default function TabsListProvider(props: TabsListProviderProps) {
     registerHighlightChangeHandler,
     registerSelectionChangeHandler,
     registerItem,
-    unregisterItem,
     totalSubitemCount,
   } = value;
 
@@ -56,9 +55,8 @@ export default function TabsListProvider(props: TabsListProviderProps) {
         getItemIndex,
         registerItem,
         totalSubitemCount,
-        unregisterItem,
       }),
-      [registerItem, getItemIndex, unregisterItem, totalSubitemCount],
+      [registerItem, getItemIndex, totalSubitemCount],
     );
 
   return (
diff --git a/packages/mui-base/src/utils/useCompound.test.tsx b/packages/mui-base/src/utils/useCompound.test.tsx
index 26357c48c50bdc..88157bea3ef177 100644
--- a/packages/mui-base/src/utils/useCompound.test.tsx
+++ b/packages/mui-base/src/utils/useCompound.test.tsx
@@ -1,7 +1,8 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { render } from 'test/utils';
-import { CompoundComponentContext, useCompoundParent, useCompoundItem } from './useCompound';
+import { CompoundComponentContext, useCompoundParent } from './useCompound';
+import { useCompoundItem } from './useCompoundItem';
 
 describe('compound components', () => {
   describe('useCompoundParent', () => {
@@ -166,5 +167,41 @@ describe('compound components', () => {
         expect(child.innerHTML).to.equal(`${index + 1} of 4`);
       });
     });
+
+    it('gets assigned a generated id if none is provided', () => {
+      function Parent(props: React.PropsWithChildren<{}>) {
+        const { children } = props;
+        const { contextValue } = useCompoundParent<number, null>();
+
+        return (
+          <CompoundComponentContext.Provider value={contextValue}>
+            <ul>{children}</ul>
+          </CompoundComponentContext.Provider>
+        );
+      }
+
+      function idGenerator(existingIds: Set<string>) {
+        return `item-${existingIds.size}`;
+      }
+
+      function Child() {
+        const { id } = useCompoundItem<string, null>(undefined, null, idGenerator);
+
+        return <li>{id}</li>;
+      }
+
+      const { getAllByRole } = render(
+        <Parent>
+          <Child />
+          <Child />
+          <Child />
+        </Parent>,
+      );
+
+      const children = getAllByRole('listitem');
+      expect(children[0].innerHTML).to.equal('item-0');
+      expect(children[1].innerHTML).to.equal('item-1');
+      expect(children[2].innerHTML).to.equal('item-2');
+    });
   });
 });
diff --git a/packages/mui-base/src/utils/useCompound.ts b/packages/mui-base/src/utils/useCompound.ts
index 76d1bc7dee7af3..c5e4f540c41a66 100644
--- a/packages/mui-base/src/utils/useCompound.ts
+++ b/packages/mui-base/src/utils/useCompound.ts
@@ -1,9 +1,44 @@
 import * as React from 'react';
 
+interface RegisterItemReturnValue<Key> {
+  /**
+   * The id of the item.
+   * If the `id` was `undefined`, an id from the `missingKeyGenerator` will be used.
+   */
+  id: Key;
+  /**
+   * A function that unregisters the item.
+   */
+  unregister: () => void;
+}
+
 export type CompoundComponentContextValue<Key, Subitem> = {
-  registerItem: (id: Key, item: Subitem) => void;
-  unregisterItem: (id: Key) => void;
+  /**
+   * Registers an item with the parent.
+   * This should be called during the effect phase of the child component.
+   * The `itemMetadata` should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
+   *
+   * @param id Id of the item.
+   * @param itemMetadata Arbitrary metadata to pass to the parent component.
+   * @param missingKeyGenerator A function that generates a unique id for the item.
+   *   It is called with the set of the ids of all the items that have already been registered.
+   *   Return `existingKeys.size` if you want to use the index of the new item as the id.
+   * @returns A function that unregisters the item.
+   */
+  registerItem: (
+    id: Key | undefined,
+    item: Subitem,
+    missingKeyGenerator?: (existingKeys: Set<Key>) => Key,
+  ) => RegisterItemReturnValue<Key>;
+  /**
+   * Returns the 0-based index of the item in the parent component's list of registered items.
+   *
+   * @param id id of the item.
+   */
   getItemIndex: (id: Key) => number;
+  /**
+   * The total number of items registered with the parent.
+   */
   totalSubitemCount: number;
 };
 
@@ -41,16 +76,10 @@ export interface UseCompoundParentReturnValue<Key, Subitem> {
  */
 export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<Key, Subitem> {
   const [subitems, setSubitems] = React.useState(new Map<Key, Subitem>());
-
-  const registerItem = React.useCallback(function registerItem(id: Key, item: Subitem) {
-    setSubitems((previousState) => {
-      const newState = new Map(previousState);
-      newState.set(id, item);
-      return newState;
-    });
-  }, []);
+  const subitemKeys = React.useRef(new Set<Key>());
 
   const unregisterItem = React.useCallback(function unregisterItem(id: Key) {
+    subitemKeys.current.delete(id);
     setSubitems((previousState) => {
       const newState = new Map(previousState);
       newState.delete(id);
@@ -58,6 +87,40 @@ export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<
     });
   }, []);
 
+  const registerItem = React.useCallback(
+    function registerItem(
+      id: Key | undefined,
+      item: Subitem,
+      missingKeyGenerator?: (existingKeys: Set<Key>) => Key,
+    ) {
+      let providedOrGeneratedId: Key;
+      if (id === undefined) {
+        if (missingKeyGenerator === undefined) {
+          throw new Error(
+            "The compound component's child doesn't have a key. You need to provide a missingKeyGenerator to generate it.",
+          );
+        }
+
+        providedOrGeneratedId = missingKeyGenerator(subitemKeys.current);
+      } else {
+        providedOrGeneratedId = id;
+      }
+
+      subitemKeys.current.add(providedOrGeneratedId);
+      setSubitems((previousState) => {
+        const newState = new Map(previousState);
+        newState.set(providedOrGeneratedId, item);
+        return newState;
+      });
+
+      return {
+        id: providedOrGeneratedId,
+        unregister: () => unregisterItem(providedOrGeneratedId),
+      };
+    },
+    [unregisterItem],
+  );
+
   const getItemIndex = React.useCallback(
     function getItemIndex(id: Key) {
       return Array.from(subitems.keys()).indexOf(id);
@@ -70,58 +133,7 @@ export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<
       getItemIndex,
       registerItem,
       totalSubitemCount: subitems.size,
-      unregisterItem,
     },
     subitems,
   };
 }
-
-export interface UseCompoundItemReturnValue {
-  /**
-   * The 0-based index of the child component in the parent component's list of registered children.
-   */
-  index: number;
-  /**
-   * The total number of child components registered with the parent component.
-   */
-  totalItemCount: number;
-}
-
-/**
- * Registers a child component with the parent component.
- *
- * @param id A unique key for the child component. If the `id` is `undefined`, the registration logic will not run (this can sometimes be the case during SSR).
- * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
- *
- * @ignore - internal hook.
- */
-export function useCompoundItem<Key, Subitem>(
-  id: Key | undefined,
-  itemMetadata: Subitem,
-): UseCompoundItemReturnValue {
-  const context = React.useContext(CompoundComponentContext) as CompoundComponentContextValue<
-    Key,
-    Subitem
-  >;
-
-  if (context === null) {
-    throw new Error('useCompoundItem must be used within a useCompoundParent');
-  }
-
-  const { registerItem, unregisterItem } = context;
-
-  React.useEffect(() => {
-    if (id === undefined) {
-      return () => {};
-    }
-
-    registerItem(id, itemMetadata);
-
-    return () => unregisterItem(id);
-  }, [id, registerItem, unregisterItem, itemMetadata]);
-
-  return {
-    index: id !== undefined ? context.getItemIndex(id) : -1,
-    totalItemCount: context.totalSubitemCount,
-  };
-}
diff --git a/packages/mui-base/src/utils/useCompoundItem.ts b/packages/mui-base/src/utils/useCompoundItem.ts
new file mode 100644
index 00000000000000..6a19b71de5a45a
--- /dev/null
+++ b/packages/mui-base/src/utils/useCompoundItem.ts
@@ -0,0 +1,63 @@
+import * as React from 'react';
+import { unstable_useEnhancedEffect as useEnhancedEffect } from '@mui/utils';
+import { CompoundComponentContext, CompoundComponentContextValue } from './useCompound';
+
+export interface UseCompoundItemReturnValue<Key> {
+  id: Key | undefined;
+  /**
+   * The 0-based index of the child component in the parent component's list of registered children.
+   */
+  index: number;
+  /**
+   * The total number of child components registered with the parent component.
+   * This value will be correct after the effect phase of the component (as children are registered with the parent during the effect phase).
+   */
+  totalItemCount: number;
+}
+
+/**
+ * Registers a child component with the parent component.
+ *
+ * @param id A unique key for the child component. If the `id` is `undefined`, the registration logic will not run (this can sometimes be the case during SSR).
+ * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
+ *
+ * @ignore - internal hook.
+ */
+export function useCompoundItem<Key, Subitem>(
+  id: Key | undefined,
+  itemMetadata: Subitem,
+  missingKeyGenerator: (existingKeys: Set<Key>) => Key,
+): UseCompoundItemReturnValue<Key>;
+export function useCompoundItem<Key, Subitem>(
+  id: Key,
+  itemMetadata: Subitem,
+): UseCompoundItemReturnValue<Key>;
+export function useCompoundItem<Key, Subitem>(
+  id: Key | undefined,
+  itemMetadata: Subitem,
+  missingKeyGenerator?: (existingKeys: Set<Key>) => Key,
+): UseCompoundItemReturnValue<Key> {
+  const context = React.useContext(CompoundComponentContext) as CompoundComponentContextValue<
+    Key,
+    Subitem
+  >;
+
+  if (context === null) {
+    throw new Error('useCompoundItem must be used within a useCompoundParent');
+  }
+
+  const { registerItem } = context;
+  const [registeredId, setRegisteredId] = React.useState(id);
+
+  useEnhancedEffect(() => {
+    const { id: returnedId, unregister } = registerItem(id, itemMetadata, missingKeyGenerator);
+    setRegisteredId(returnedId);
+    return unregister;
+  }, [registerItem, itemMetadata, missingKeyGenerator, id]);
+
+  return {
+    id: registeredId,
+    index: registeredId !== undefined ? context.getItemIndex(registeredId) : -1,
+    totalItemCount: context.totalSubitemCount,
+  };
+}
diff --git a/packages/mui-joy/src/MenuItem/MenuItem.test.js b/packages/mui-joy/src/MenuItem/MenuItem.test.js
index 050eed98632bdd..fcc5f4cd0016b9 100644
--- a/packages/mui-joy/src/MenuItem/MenuItem.test.js
+++ b/packages/mui-joy/src/MenuItem/MenuItem.test.js
@@ -24,6 +24,7 @@ const testContext = {
   getItemProps: () => ({}),
   registerItem: () => {},
   unregisterItem: () => {},
+  preregisterItem: () => {},
   open: false,
   registerHighlightChangeHandler: () => () => {},
 };

From 8967e1614846c9edec52d891fe09298903c0da52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 30 Mar 2023 15:52:18 +0200
Subject: [PATCH 13/49] Sync ids between tabs and tab panels

---
 docs/pages/base/api/tab-panel-unstyled.json   |  7 +--
 docs/pages/base/api/tab-unstyled.json         |  7 +--
 docs/pages/base/api/use-tab-panel.json        |  6 +--
 docs/pages/base/api/use-tab.json              |  8 ++-
 docs/pages/base/api/use-tabs.json             |  7 ---
 .../api-docs/use-tab/use-tab.json             |  1 +
 .../TabPanelUnstyled.test.tsx                 | 26 ++++++----
 .../src/TabPanelUnstyled/TabPanelUnstyled.tsx |  2 +-
 .../TabPanelUnstyled.types.ts                 |  2 +-
 .../src/TabUnstyled/TabUnstyled.test.tsx      | 20 +++++++-
 .../TabsListUnstyled.test.tsx                 | 20 +++++++-
 .../mui-base/src/TabsUnstyled/TabsContext.ts  | 38 ++++++--------
 .../src/TabsUnstyled/TabsUnstyled.test.tsx    | 51 +++++++++++++++++++
 packages/mui-base/src/useTab/useTab.ts        | 15 +++---
 packages/mui-base/src/useTab/useTab.types.ts  |  5 ++
 .../mui-base/src/useTabPanel/useTabPanel.ts   | 31 ++++++++---
 .../src/useTabPanel/useTabPanel.types.ts      |  3 +-
 .../mui-base/src/useTabs/TabsProvider.tsx     | 19 +++++--
 packages/mui-base/src/useTabs/useTabs.ts      | 35 ++++++++++---
 .../mui-base/src/useTabs/useTabs.types.ts     |  1 -
 .../mui-base/src/useTabsList/useTabsList.ts   | 14 ++++-
 21 files changed, 226 insertions(+), 92 deletions(-)

diff --git a/docs/pages/base/api/tab-panel-unstyled.json b/docs/pages/base/api/tab-panel-unstyled.json
index c1ef1a14d84d2b..e1f1027d5d8f41 100644
--- a/docs/pages/base/api/tab-panel-unstyled.json
+++ b/docs/pages/base/api/tab-panel-unstyled.json
@@ -1,9 +1,5 @@
 {
   "props": {
-    "value": {
-      "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
-      "required": true
-    },
     "children": { "type": { "name": "node" } },
     "component": { "type": { "name": "elementType" } },
     "slotProps": {
@@ -13,7 +9,8 @@
     "slots": {
       "type": { "name": "shape", "description": "{ root?: elementType }" },
       "default": "{}"
-    }
+    },
+    "value": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } }
   },
   "name": "TabPanelUnstyled",
   "styles": { "classes": [], "globalClasses": {}, "name": null },
diff --git a/docs/pages/base/api/tab-unstyled.json b/docs/pages/base/api/tab-unstyled.json
index 38caa81d44ef05..4faa9060244389 100644
--- a/docs/pages/base/api/tab-unstyled.json
+++ b/docs/pages/base/api/tab-unstyled.json
@@ -1,9 +1,5 @@
 {
   "props": {
-    "value": {
-      "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
-      "required": true
-    },
     "action": {
       "type": {
         "name": "union",
@@ -20,7 +16,8 @@
     "slots": {
       "type": { "name": "shape", "description": "{ root?: elementType }" },
       "default": "{}"
-    }
+    },
+    "value": { "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" } }
   },
   "name": "TabUnstyled",
   "styles": { "classes": [], "globalClasses": {}, "name": null },
diff --git a/docs/pages/base/api/use-tab-panel.json b/docs/pages/base/api/use-tab-panel.json
index c26a0cfc8c7dd0..99426daf8a3639 100644
--- a/docs/pages/base/api/use-tab-panel.json
+++ b/docs/pages/base/api/use-tab-panel.json
@@ -1,9 +1,7 @@
 {
   "parameters": {
-    "value": {
-      "type": { "name": "number | string", "description": "number | string" },
-      "required": true
-    }
+    "id": { "type": { "name": "string", "description": "string" } },
+    "value": { "type": { "name": "number | string", "description": "number | string" } }
   },
   "returnValue": {
     "getRootProps": {
diff --git a/docs/pages/base/api/use-tab.json b/docs/pages/base/api/use-tab.json
index f1333c1b2f1ef0..a34bb3ba596c21 100644
--- a/docs/pages/base/api/use-tab.json
+++ b/docs/pages/base/api/use-tab.json
@@ -1,11 +1,9 @@
 {
   "parameters": {
-    "value": {
-      "type": { "name": "number | string", "description": "number | string" },
-      "required": true
-    },
     "disabled": { "type": { "name": "boolean", "description": "boolean" } },
-    "ref": { "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" } }
+    "id": { "type": { "name": "string", "description": "string" } },
+    "ref": { "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" } },
+    "value": { "type": { "name": "number | string", "description": "number | string" } }
   },
   "returnValue": {
     "active": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
diff --git a/docs/pages/base/api/use-tabs.json b/docs/pages/base/api/use-tabs.json
index 221b1a11ea62b4..9321bb2f5ca546 100644
--- a/docs/pages/base/api/use-tabs.json
+++ b/docs/pages/base/api/use-tabs.json
@@ -32,13 +32,6 @@
     "contextValue": {
       "type": { "name": "TabsProviderValue", "description": "TabsProviderValue" },
       "required": true
-    },
-    "tabPanels": {
-      "type": {
-        "name": "Map&lt;string | number, string&gt;",
-        "description": "Map&lt;string | number, string&gt;"
-      },
-      "required": true
     }
   },
   "name": "useTabs",
diff --git a/docs/translations/api-docs/use-tab/use-tab.json b/docs/translations/api-docs/use-tab/use-tab.json
index 73324af032c9f5..e45aaf2dbd40dd 100644
--- a/docs/translations/api-docs/use-tab/use-tab.json
+++ b/docs/translations/api-docs/use-tab/use-tab.json
@@ -2,6 +2,7 @@
   "hookDescription": "",
   "parametersDescriptions": {
     "disabled": "If <code>true</code>, the tab will be disabled.",
+    "id": "The id of the tab.\nIf not provided, it will be automatically generated.",
     "ref": "Ref to the DOM element associated with the tab.",
     "value": "The value of the tab.\nIt's used to associate the tab with a tab panel(s) with the same value."
   },
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
index 7515487a5ee9c8..9716f7389b2e24 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
@@ -1,29 +1,37 @@
 import * as React from 'react';
 import { createMount, createRenderer, describeConformanceUnstyled } from 'test/utils';
-import { TabsContext } from '@mui/base/TabsUnstyled';
 import TabPanelUnstyled, { tabPanelUnstyledClasses } from '@mui/base/TabPanelUnstyled';
+import { TabsProvider, TabsProviderValue } from '../useTabs';
 
 describe('<TabPanelUnstyled />', () => {
   const mount = createMount();
   const { render } = createRenderer();
 
+  const tabsProviderDefaultValue: TabsProviderValue = {
+    value: '1',
+    onSelected: () => {},
+    registerTabIdLookup() {},
+    getTabId: () => '',
+    getTabPanelId: () => '',
+    getItemIndex: () => 0,
+    registerItem: () => ({ id: 0, unregister: () => {} }),
+    totalSubitemCount: 1,
+    direction: 'ltr',
+    orientation: 'horizontal',
+    selectionFollowsFocus: false,
+  };
+
   describeConformanceUnstyled(<TabPanelUnstyled value="1" />, () => ({
     inheritComponent: 'div',
     render: (node) => {
       const { container, ...other } = render(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
-          {node}
-        </TabsContext.Provider>,
+        <TabsProvider value={tabsProviderDefaultValue}>{node}</TabsProvider>,
       );
 
       return { container, ...other };
     },
     mount: (node: any) => {
-      const wrapper = mount(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
-          {node}
-        </TabsContext.Provider>,
-      );
+      const wrapper = mount(<TabsProvider value={tabsProviderDefaultValue}>{node}</TabsProvider>);
       return wrapper.childAt(0);
     },
     refInstanceof: window.HTMLDivElement,
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
index 80bbe720a47734..0690dcc75cd13b 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
@@ -95,7 +95,7 @@ TabPanelUnstyled.propTypes /* remove-proptypes */ = {
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
    */
-  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]).isRequired,
+  value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
 } as any;
 
 export default TabPanelUnstyled;
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
index 072c6a73b68d19..0a722f7f79e629 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
@@ -14,7 +14,7 @@ export interface TabPanelUnstyledOwnProps {
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
    */
-  value: number | string;
+  value?: number | string;
   /**
    * The components used for each slot inside the TabPanel.
    * Either a string to use a HTML element or a component.
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
index 884ae8f1729a2d..4a7ae5e0b97b0e 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
@@ -24,7 +24,15 @@ describe('<TabUnstyled />', () => {
     inheritComponent: 'div',
     render: (node) => {
       const { container, ...other } = render(
-        <TabsContext.Provider value={{ idPrefix: '', value: 0, onSelected() {} }}>
+        <TabsContext.Provider
+          value={{
+            value: 0,
+            onSelected() {},
+            registerTabIdLookup() {},
+            getTabId: () => '',
+            getTabPanelId: () => '',
+          }}
+        >
           <TabsListProvider value={testTabsListContext}>{node}</TabsListProvider>
         </TabsContext.Provider>,
       );
@@ -33,7 +41,15 @@ describe('<TabUnstyled />', () => {
     },
     mount: (node: any) => {
       const wrapper = mount(
-        <TabsContext.Provider value={{ idPrefix: '', value: 0, onSelected() {} }}>
+        <TabsContext.Provider
+          value={{
+            value: 0,
+            onSelected() {},
+            registerTabIdLookup() {},
+            getTabId: () => '',
+            getTabPanelId: () => '',
+          }}
+        >
           <TabsListProvider value={testTabsListContext}>{node}</TabsListProvider>
         </TabsContext.Provider>,
       );
diff --git a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.test.tsx b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.test.tsx
index 1467f7bdbcc85f..0f9ed6926be19f 100644
--- a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.test.tsx
+++ b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.test.tsx
@@ -11,7 +11,15 @@ describe('<TabsListUnstyled />', () => {
     inheritComponent: 'div',
     render: (node) => {
       const { container, ...other } = render(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
+        <TabsContext.Provider
+          value={{
+            value: '1',
+            onSelected: () => {},
+            registerTabIdLookup() {},
+            getTabId: () => '',
+            getTabPanelId: () => '',
+          }}
+        >
           {node}
         </TabsContext.Provider>,
       );
@@ -20,7 +28,15 @@ describe('<TabsListUnstyled />', () => {
     },
     mount: (node: any) => {
       const wrapper = mount(
-        <TabsContext.Provider value={{ value: '1', idPrefix: '1', onSelected: () => {} }}>
+        <TabsContext.Provider
+          value={{
+            value: '1',
+            onSelected: () => {},
+            registerTabIdLookup() {},
+            getTabId: () => '',
+            getTabPanelId: () => '',
+          }}
+        >
           {node}
         </TabsContext.Provider>,
       );
diff --git a/packages/mui-base/src/TabsUnstyled/TabsContext.ts b/packages/mui-base/src/TabsUnstyled/TabsContext.ts
index 30ea4501ded99b..38b0d6a233dd80 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsContext.ts
+++ b/packages/mui-base/src/TabsUnstyled/TabsContext.ts
@@ -1,10 +1,6 @@
 import * as React from 'react';
 
 export interface TabsContextValue {
-  /**
-   * Id used as a prefix for the current Tabs.
-   */
-  idPrefix: string | undefined;
   /**
    * The currently selected tab's value.
    */
@@ -18,14 +14,28 @@ export interface TabsContextValue {
    */
   orientation?: 'horizontal' | 'vertical';
   /**
-   * The direction of the text.
+   * The direction of the tabs.
    */
   direction?: 'ltr' | 'rtl';
+  /**
+   * Registers a function that returns the id of the tab with the given value.
+   */
+  registerTabIdLookup: (lookupFunction: (id: string | number) => string | undefined) => void;
   /**
    * If `true` the selected tab changes on focus. Otherwise it only
    * changes on activation.
    */
   selectionFollowsFocus?: boolean;
+  /**
+   * Gets the id of the tab with the given value.
+   * @param value Value to find the tab for.
+   */
+  getTabId: (value: number | string) => string | undefined;
+  /**
+   * Gets the id of the tab panel with the given value.
+   * @param value Value to find the tab panel for.
+   */
+  getTabPanelId: (value: number | string) => string | undefined;
 }
 
 /**
@@ -37,7 +47,7 @@ if (process.env.NODE_ENV !== 'production') {
   Context.displayName = 'TabsContext';
 }
 
-export function useTabContext() {
+export function useTabsContext() {
   const context = React.useContext(Context);
   if (context == null) {
     throw new Error('No TabsContext provided');
@@ -46,20 +56,4 @@ export function useTabContext() {
   return context;
 }
 
-export function getPanelId(context: TabsContextValue, value: number | string | false) {
-  const { idPrefix } = context;
-  if (idPrefix === null) {
-    return null;
-  }
-  return `${context.idPrefix}-P-${value}`;
-}
-
-export function getTabId(context: TabsContextValue, value: number | string | false) {
-  const { idPrefix } = context;
-  if (idPrefix === null) {
-    return null;
-  }
-  return `${context.idPrefix}-T-${value}`;
-}
-
 export default Context;
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
index 064b66924036cf..3187eb21f0e765 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
@@ -12,6 +12,7 @@ import {
 import Tab from '@mui/base/TabUnstyled';
 import Tabs, { tabsUnstyledClasses as classes, TabsUnstyledProps } from '@mui/base/TabsUnstyled';
 import TabsList from '@mui/base/TabsListUnstyled';
+import TabPanel from '@mui/base/TabPanelUnstyled';
 
 describe('<TabsUnstyled />', () => {
   const mount = createMount();
@@ -104,6 +105,56 @@ describe('<TabsUnstyled />', () => {
 
       expect(getAllByRole('tab').map((tab) => tab.tabIndex)).to.have.ordered.members([0, -1]);
     });
+
+    it('sets the aria-labelledby attribute on tab panels to the corresponding tab id', () => {
+      const { getAllByRole } = render(
+        <Tabs>
+          <TabsList>
+            <Tab value="tab-0" />
+            <Tab value="tab-1" id="explicit-tab-id-1" />
+            <Tab />
+            <Tab id="explicit-tab-id-3" />
+          </TabsList>
+          <TabPanel value="tab-1" />
+          <TabPanel value="tab-0" />
+          <TabPanel />
+          <TabPanel />
+        </Tabs>,
+      );
+
+      const tabs = getAllByRole('tab');
+      const tabPanels = getAllByRole('tabpanel');
+
+      expect(tabPanels[0]).to.have.attribute('aria-labelledby', tabs[1].id);
+      expect(tabPanels[1]).to.have.attribute('aria-labelledby', tabs[0].id);
+      expect(tabPanels[2]).to.have.attribute('aria-labelledby', tabs[2].id);
+      expect(tabPanels[3]).to.have.attribute('aria-labelledby', tabs[3].id);
+    });
+
+    it('sets the aria-controls attribute on tabs to the corresponding tab panel id', () => {
+      const { getAllByRole } = render(
+        <Tabs>
+          <TabsList>
+            <Tab value="tab-0" />
+            <Tab value="tab-1" id="explicit-tab-id-1" />
+            <Tab />
+            <Tab id="explicit-tab-id-3" />
+          </TabsList>
+          <TabPanel value="tab-1" />
+          <TabPanel value="tab-0" />
+          <TabPanel />
+          <TabPanel />
+        </Tabs>,
+      );
+
+      const tabs = getAllByRole('tab');
+      const tabPanels = getAllByRole('tabpanel');
+
+      expect(tabs[0]).to.have.attribute('aria-controls', tabPanels[1].id);
+      expect(tabs[1]).to.have.attribute('aria-controls', tabPanels[0].id);
+      expect(tabs[2]).to.have.attribute('aria-controls', tabPanels[2].id);
+      expect(tabs[3]).to.have.attribute('aria-controls', tabPanels[3].id);
+    });
   });
 
   describe('prop: value', () => {
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index 9ea28cef1df883..14a2cdd418fb79 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { unstable_useId as useId, unstable_useForkRef as useForkRef } from '@mui/utils';
-import { useTabContext } from '../TabsUnstyled';
+import { useTabsContext } from '../TabsUnstyled';
 import { UseTabParameters, UseTabReturnValue, UseTabRootSlotProps } from './useTab.types';
 import { EventHandlers } from '../utils';
 import { useCompoundItem } from '../utils/useCompoundItem';
@@ -23,13 +23,14 @@ function tabValueGenerator(otherTabValues: Set<string | number>) {
  * - [useTab API](https://mui.com/base/react-tabs/hooks-api/#use-tab)
  */
 function useTab(parameters: UseTabParameters): UseTabReturnValue {
-  const { value: valueParam, ref: externalRef, disabled = false } = parameters;
+  const { value: valueParam, ref: externalRef, disabled = false, id: idParam } = parameters;
 
   const tabRef = React.useRef<HTMLElement>(null);
+  const id = useId(idParam);
 
-  const { value: selectedValue, idPrefix = '', selectionFollowsFocus } = useTabContext();
+  const { value: selectedValue, selectionFollowsFocus, getTabPanelId } = useTabsContext();
 
-  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef }), [disabled, tabRef]);
+  const tabMetadata = React.useMemo(() => ({ disabled, ref: tabRef, id }), [disabled, tabRef, id]);
 
   const {
     id: value,
@@ -58,7 +59,7 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
 
   const handleRef = useForkRef(tabRef, externalRef, listItemRefHandler, buttonRefHandler);
 
-  const tabId = idPrefix + useId();
+  const tabPanelId = value !== undefined ? getTabPanelId(value) : undefined;
 
   const getRootProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
@@ -76,9 +77,9 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
     return {
       ...resolvedButtonProps,
       role: 'tab',
-      'aria-controls': 'not-implemented-yet',
+      'aria-controls': tabPanelId,
       'aria-selected': selected,
-      id: tabId,
+      id,
       ref: handleRef,
     };
   };
diff --git a/packages/mui-base/src/useTab/useTab.types.ts b/packages/mui-base/src/useTab/useTab.types.ts
index 0d4a8d4250fb85..397ec541770ac6 100644
--- a/packages/mui-base/src/useTab/useTab.types.ts
+++ b/packages/mui-base/src/useTab/useTab.types.ts
@@ -11,6 +11,11 @@ export interface UseTabParameters {
    * If `true`, the tab will be disabled.
    */
   disabled?: boolean;
+  /**
+   * The id of the tab.
+   * If not provided, it will be automatically generated.
+   */
+  id?: string;
   /**
    * Ref to the DOM element associated with the tab.
    */
diff --git a/packages/mui-base/src/useTabPanel/useTabPanel.ts b/packages/mui-base/src/useTabPanel/useTabPanel.ts
index 8d17319e063b4d..b422a4dd8b761c 100644
--- a/packages/mui-base/src/useTabPanel/useTabPanel.ts
+++ b/packages/mui-base/src/useTabPanel/useTabPanel.ts
@@ -1,5 +1,12 @@
-import { useTabContext, getPanelId, getTabId } from '../TabsUnstyled';
+import { unstable_useId as useId } from '@mui/utils';
+import { useTabsContext } from '../TabsUnstyled';
+import { useCompoundItem } from '../utils/useCompoundItem';
 import { UseTabPanelParameters, UseTabPanelReturnValue } from './useTabPanel.types';
+
+function tabPanelValueGenerator(otherTabPanelValues: Set<string | number>) {
+  return otherTabPanelValues.size;
+}
+
 /**
  *
  * Demos:
@@ -11,20 +18,30 @@ import { UseTabPanelParameters, UseTabPanelReturnValue } from './useTabPanel.typ
  * - [useTabPanel API](https://mui.com/base/react-tabs/hooks-api/#use-tab-panel)
  */
 function useTabPanel(parameters: UseTabPanelParameters): UseTabPanelReturnValue {
-  const { value } = parameters;
+  const { value: valueParam, id: idParam } = parameters;
 
-  const context = useTabContext();
+  const context = useTabsContext();
   if (context === null) {
     throw new Error('No TabContext provided');
   }
 
-  const hidden = value !== context.value;
-  const id = getPanelId(context, value);
-  const tabId = getTabId(context, value);
+  const { value: selectedTabValue, getTabId } = context;
+
+  const id = useId(idParam);
+
+  const { id: value } = useCompoundItem<string | number, string | undefined>(
+    valueParam,
+    id,
+    tabPanelValueGenerator,
+  );
+
+  const hidden = value !== selectedTabValue;
+
+  const correspondingTabId = value !== undefined ? getTabId(value) : undefined;
 
   const getRootProps = () => {
     return {
-      'aria-labelledby': tabId ?? undefined,
+      'aria-labelledby': correspondingTabId ?? undefined,
       hidden,
       id: id ?? undefined,
     };
diff --git a/packages/mui-base/src/useTabPanel/useTabPanel.types.ts b/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
index 73b11362a06e03..1149f31866a1a3 100644
--- a/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
+++ b/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
@@ -1,8 +1,9 @@
 export interface UseTabPanelParameters {
+  id?: string;
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
    */
-  value: number | string;
+  value?: number | string;
 }
 
 export interface UseTabPanelRootSlotProps {
diff --git a/packages/mui-base/src/useTabs/TabsProvider.tsx b/packages/mui-base/src/useTabs/TabsProvider.tsx
index e61686266c1729..65ac2629f5cf4d 100644
--- a/packages/mui-base/src/useTabs/TabsProvider.tsx
+++ b/packages/mui-base/src/useTabs/TabsProvider.tsx
@@ -20,13 +20,15 @@ export default function TabsProvider(props: TabsProviderProps) {
   const {
     direction,
     getItemIndex,
-    idPrefix,
     onSelected,
     orientation,
     registerItem,
+    registerTabIdLookup,
     selectionFollowsFocus,
     totalSubitemCount,
     value,
+    getTabId,
+    getTabPanelId,
   } = valueProp;
 
   const compoundComponentContextValue: CompoundComponentContextValue<string | number, string> =
@@ -42,13 +44,24 @@ export default function TabsProvider(props: TabsProviderProps) {
   const tabsContextValue: TabsContextValue = React.useMemo(
     () => ({
       direction,
-      idPrefix,
+      getTabId,
+      getTabPanelId,
       onSelected,
       orientation,
+      registerTabIdLookup,
       selectionFollowsFocus,
       value,
     }),
-    [direction, idPrefix, onSelected, orientation, selectionFollowsFocus, value],
+    [
+      direction,
+      getTabId,
+      getTabPanelId,
+      onSelected,
+      orientation,
+      registerTabIdLookup,
+      selectionFollowsFocus,
+      value,
+    ],
   );
 
   return (
diff --git a/packages/mui-base/src/useTabs/useTabs.ts b/packages/mui-base/src/useTabs/useTabs.ts
index 186e43ea84a27d..12b992098087c1 100644
--- a/packages/mui-base/src/useTabs/useTabs.ts
+++ b/packages/mui-base/src/useTabs/useTabs.ts
@@ -1,13 +1,16 @@
 import * as React from 'react';
-import { unstable_useControlled as useControlled, unstable_useId as useId } from '@mui/utils';
+import { unstable_useControlled as useControlled } from '@mui/utils';
 import { UseTabsParameters, UseTabsReturnValue } from './useTabs.types';
 import { useCompoundParent } from '../utils/useCompound';
 
 export interface TabMetadata {
   disabled: boolean;
+  id: string | undefined;
   ref: React.RefObject<HTMLElement>;
 }
 
+type IdLookupFunction = (id: string | number) => string | undefined;
+
 /**
  *
  * Demos:
@@ -35,8 +38,6 @@ function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
     state: 'value',
   });
 
-  const idPrefix = useId();
-
   const onSelected = React.useCallback(
     (event: React.SyntheticEvent | null, newValue: string | number | null) => {
       setValue(newValue);
@@ -47,18 +48,36 @@ function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
 
   const { subitems: tabPanels, contextValue: compoundComponentContextValue } = useCompoundParent<
     string | number,
-    string
+    string | undefined
   >();
 
+  const tabIdLookup = React.useRef<IdLookupFunction>(() => undefined);
+
+  const getTabPanelId = React.useCallback(
+    (tabValue: string | number) => {
+      return tabPanels.get(tabValue);
+    },
+    [tabPanels],
+  );
+
+  const getTabId = React.useCallback((tabPanelId: string | number) => {
+    return tabIdLookup.current(tabPanelId);
+  }, []);
+
+  const registerTabIdLookup = React.useCallback((lookupFunction: IdLookupFunction) => {
+    tabIdLookup.current = lookupFunction;
+  }, []);
+
   return {
-    tabPanels,
     contextValue: {
-      idPrefix,
-      value,
+      direction,
+      getTabId,
+      getTabPanelId,
       onSelected,
       orientation,
-      direction,
+      registerTabIdLookup,
       selectionFollowsFocus,
+      value,
       ...compoundComponentContextValue,
     },
   };
diff --git a/packages/mui-base/src/useTabs/useTabs.types.ts b/packages/mui-base/src/useTabs/useTabs.types.ts
index 6ca1f696fb8c2f..d30a995bf54f0e 100644
--- a/packages/mui-base/src/useTabs/useTabs.types.ts
+++ b/packages/mui-base/src/useTabs/useTabs.types.ts
@@ -32,7 +32,6 @@ export interface UseTabsParameters {
 }
 
 export interface UseTabsReturnValue {
-  tabPanels: Map<string | number, string>;
   /**
    * Returns the values to be passed to the tabs provider.
    */
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 2da6e568419777..6ad2e53acf0322 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { useTabContext } from '../TabsUnstyled';
+import { useTabsContext } from '../TabsUnstyled';
 import {
   TabsListContextValue,
   UseTabsListParameters,
@@ -37,14 +37,24 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     onSelected,
     orientation = 'horizontal',
     value,
+    registerTabIdLookup,
     selectionFollowsFocus,
-  } = useTabContext();
+  } = useTabsContext();
 
   const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
     string | number,
     TabMetadata
   >();
 
+  const tabIdLookup = React.useCallback(
+    (tabValue: string | number) => {
+      return subitems.get(tabValue)?.id;
+    },
+    [subitems],
+  );
+
+  registerTabIdLookup(tabIdLookup);
+
   const subitemKeys = React.useMemo(() => Array.from(subitems.keys()), [subitems]);
 
   const getTabElement = React.useCallback(

From f266cd6a45ce9c09f6a471e562d7e33aa9a0dced Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 30 Mar 2023 23:22:37 +0200
Subject: [PATCH 14/49] Fix errors in Joy

---
 .../MenuItemUnstyled.test.tsx                 |  2 +-
 .../OptionUnstyled/OptionUnstyled.test.tsx    |  4 +--
 .../src/OptionUnstyled/OptionUnstyled.tsx     | 11 +++++--
 .../TabPanelUnstyled.test.tsx                 |  2 +-
 .../src/TabUnstyled/TabUnstyled.test.tsx      |  2 +-
 packages/mui-base/src/useMenu/index.ts        |  2 ++
 packages/mui-base/src/useMenu/useMenu.ts      |  4 +--
 .../mui-base/src/useMenu/useMenu.types.ts     |  5 +++-
 packages/mui-base/src/useOption/useOption.ts  |  3 +-
 .../mui-base/src/useOption/useOption.types.ts |  1 +
 packages/mui-base/src/useTab/useTab.ts        |  4 +++
 packages/mui-base/src/useTab/useTab.types.ts  | 10 +++++++
 packages/mui-base/src/utils/useCompound.ts    | 11 ++++---
 .../mui-base/src/utils/useCompoundItem.ts     |  4 +--
 packages/mui-joy/src/List/List.tsx            |  7 -----
 packages/mui-joy/src/ListItem/ListItem.tsx    |  5 +---
 packages/mui-joy/src/Menu/Menu.tsx            | 26 ++++++++---------
 .../mui-joy/src/MenuItem/MenuItem.test.js     | 29 +++++++------------
 packages/mui-joy/src/MenuList/MenuList.tsx    |  9 +++---
 packages/mui-joy/src/Option/Option.tsx        | 11 +++++--
 packages/mui-joy/src/Option/OptionProps.ts    | 23 ++++++++++++---
 packages/mui-joy/src/Select/Select.test.tsx   | 10 +++----
 packages/mui-joy/src/Select/Select.tsx        | 28 +++++++-----------
 packages/mui-joy/src/Tab/Tab.test.tsx         | 23 +++++++++++----
 packages/mui-joy/src/TabList/TabList.test.tsx |  8 ++---
 .../mui-joy/src/TabPanel/TabPanel.test.tsx    |  8 ++---
 packages/mui-joy/src/TabPanel/TabPanel.tsx    |  4 +--
 27 files changed, 145 insertions(+), 111 deletions(-)

diff --git a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
index 1e9d1f3c99f59f..1c0602078c39e9 100644
--- a/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
+++ b/packages/mui-base/src/MenuItemUnstyled/MenuItemUnstyled.test.tsx
@@ -18,7 +18,7 @@ const testContext = {
   getItemState: dummyGetItemState,
   open: false,
   registerHighlightChangeHandler: () => () => {},
-  registerItem: () => ({ id: '', unregister: () => {} }),
+  registerItem: () => ({ id: '', deregister: () => {} }),
   registerSelectionChangeHandler: () => () => {},
   totalSubitemCount: 0,
 };
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
index 0b69f45dd01125..1005a4af10ceb4 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
@@ -25,7 +25,7 @@ describe('<OptionUnstyled />', () => {
             getItemIndex: () => 0,
             getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
-            registerItem: () => ({ id: 0, unregister: () => {} }),
+            registerItem: () => ({ id: 0, deregister: () => {} }),
             registerSelectionChangeHandler: () => () => {},
             totalSubitemCount: 0,
           }}
@@ -42,7 +42,7 @@ describe('<OptionUnstyled />', () => {
             getItemIndex: () => 0,
             getItemState: dummyGetItemState,
             registerHighlightChangeHandler: () => () => {},
-            registerItem: () => ({ id: 0, unregister: () => {} }),
+            registerItem: () => ({ id: 0, deregister: () => {} }),
             registerSelectionChangeHandler: () => () => {},
             totalSubitemCount: 0,
           }}
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
index 8f088b00527b8d..b3741185472746 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
+import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import composeClasses from '../composeClasses';
 import {
   OptionUnstyledProps,
@@ -41,11 +42,17 @@ const OptionUnstyled = React.forwardRef(function OptionUnstyled<TValue>(
 
   const Root = component || slots.root || 'li';
 
+  const optionRef = React.useRef<HTMLLIElement>(null);
+  const combinedRef = useForkRef(optionRef, ref);
+
+  const computedLabel =
+    label ?? (typeof children === 'string' ? children : optionRef.current?.innerText);
+
   const { getRootProps, selected, highlighted, index } = useOption({
     disabled,
+    label: computedLabel,
+    optionRef: combinedRef,
     value,
-    optionRef: ref,
-    label: label || children,
   });
 
   const ownerState: OptionUnstyledOwnerState<TValue> = {
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
index 9716f7389b2e24..a8ce9b5decb8cf 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.test.tsx
@@ -14,7 +14,7 @@ describe('<TabPanelUnstyled />', () => {
     getTabId: () => '',
     getTabPanelId: () => '',
     getItemIndex: () => 0,
-    registerItem: () => ({ id: 0, unregister: () => {} }),
+    registerItem: () => ({ id: 0, deregister: () => {} }),
     totalSubitemCount: 1,
     direction: 'ltr',
     orientation: 'horizontal',
diff --git a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
index 4a7ae5e0b97b0e..28b85cc00bf4fa 100644
--- a/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
+++ b/packages/mui-base/src/TabUnstyled/TabUnstyled.test.tsx
@@ -10,7 +10,7 @@ describe('<TabUnstyled />', () => {
 
   const testTabsListContext: TabsListProviderValue = {
     dispatch: () => {},
-    registerItem: () => ({ id: 0, unregister: () => {} }),
+    registerItem: () => ({ id: 0, deregister: () => {} }),
     getItemIndex: () => 0,
     totalSubitemCount: 1,
     getItemState() {
diff --git a/packages/mui-base/src/useMenu/index.ts b/packages/mui-base/src/useMenu/index.ts
index fafe3ff6f6647e..5d464e91afe4e7 100644
--- a/packages/mui-base/src/useMenu/index.ts
+++ b/packages/mui-base/src/useMenu/index.ts
@@ -1,3 +1,5 @@
 export { default } from './useMenu';
 export * from './useMenu.types';
+
 export { default as MenuProvider } from './MenuProvider';
+export * from './MenuProvider';
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index c26981d90f4359..36fc653805b942 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -88,7 +88,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     [],
   );
 
-  const controlledState = React.useMemo(() => ({ open: openProp }), [openProp]);
+  const controlledProps = React.useMemo(() => ({ open: openProp }), [openProp]);
 
   const stateChangeHandler: StateChangeCallback<MenuInternalState> = React.useCallback(
     (event, field, fieldValue, reason, state) => {
@@ -109,7 +109,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     contextValue: listContextValue,
     state: { open },
   } = useList<string, MenuInternalState>({
-    controlledProps: controlledState,
+    controlledProps,
     disabledItemsFocusable: true,
     focusManagement: 'DOM',
     getItemDomElement,
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 72902022b0a3e3..4b753153e1ee13 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -14,7 +14,7 @@ export interface UseMenuParameters {
 
 export interface UseMenuReturnValue {
   /**
-   * The value for the menu context.
+   * The value to be passed into the MenuProvider.
    */
   contextValue: MenuProviderValue;
   /**
@@ -41,6 +41,9 @@ export interface UseMenuReturnValue {
    * Items in the menu listbox.
    */
   menuItems: Map<string, MenuItemMetadata>;
+  /**
+   * If `true`, the menu is open.
+   */
   open: boolean;
 }
 
diff --git a/packages/mui-base/src/useOption/useOption.ts b/packages/mui-base/src/useOption/useOption.ts
index 22740cccf50051..2db25a8671fbda 100644
--- a/packages/mui-base/src/useOption/useOption.ts
+++ b/packages/mui-base/src/useOption/useOption.ts
@@ -44,7 +44,7 @@ export default function useOption<Value>(params: UseOptionParameters<Value>): Us
 
   const { index } = useCompoundItem<Value, SelectOption<Value>>(value, selectOption);
 
-  const handleRef = useForkRef(optionRefParam, optionRef, listItemRefHandler);
+  const handleRef = useForkRef(optionRefParam, optionRef, listItemRefHandler)!;
 
   return {
     getRootProps: <Other extends EventHandlers = {}>(otherHandlers: Other = {} as Other) => ({
@@ -58,5 +58,6 @@ export default function useOption<Value>(params: UseOptionParameters<Value>): Us
     highlighted,
     index,
     selected,
+    ref: handleRef,
   };
 }
diff --git a/packages/mui-base/src/useOption/useOption.types.ts b/packages/mui-base/src/useOption/useOption.types.ts
index 5eb0820e383a89..4f2e7cc94200b6 100644
--- a/packages/mui-base/src/useOption/useOption.types.ts
+++ b/packages/mui-base/src/useOption/useOption.types.ts
@@ -24,6 +24,7 @@ export interface UseOptionReturnValue {
   getRootProps: <Other extends EventHandlers>(
     otherHandlers?: Other,
   ) => UseOptionRootSlotProps<Other>;
+  ref: React.RefCallback<HTMLElement>;
 }
 
 export type UseOptionRootSlotProps<Other extends EventHandlers = {}> =
diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
index 14a2cdd418fb79..8523579f014121 100644
--- a/packages/mui-base/src/useTab/useTab.ts
+++ b/packages/mui-base/src/useTab/useTab.ts
@@ -51,6 +51,8 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
     getRootProps: getButtonProps,
     ref: buttonRefHandler,
     active,
+    focusVisible,
+    setFocusVisible,
   } = useButton({
     disabled,
     focusableWhenDisabled: !selectionFollowsFocus,
@@ -87,11 +89,13 @@ function useTab(parameters: UseTabParameters): UseTabReturnValue {
   return {
     getRootProps,
     active,
+    focusVisible,
     highlighted,
     index,
     // the `selected` state isn't set on the server (it relies on effects to be calculated),
     // so we fall back to checking the `value` prop with the selectedValue from the TabsContext
     selected: selected || value === selectedValue,
+    setFocusVisible,
     totalTabsCount,
   };
 }
diff --git a/packages/mui-base/src/useTab/useTab.types.ts b/packages/mui-base/src/useTab/useTab.types.ts
index 397ec541770ac6..5e7979de5cb147 100644
--- a/packages/mui-base/src/useTab/useTab.types.ts
+++ b/packages/mui-base/src/useTab/useTab.types.ts
@@ -42,6 +42,11 @@ export interface UseTabReturnValue {
    * If `true`, the tab is active (as in `:active` pseudo-class; in other words, pressed).
    */
   active: boolean;
+  /**
+   * If `true`, the tab has visible focus.
+   * This is a workaround for browsers that do not support this feature natively.
+   */
+  focusVisible: boolean;
   /**
    * If `true`, the tab is highlighted.
    */
@@ -54,6 +59,11 @@ export interface UseTabReturnValue {
    * If `true`, the tab is selected.
    */
   selected: boolean;
+  /**
+   * Sets the focus-visible state of the tab.
+   * This is a workaround for browsers that do not support this feature natively.
+   */
+  setFocusVisible: React.Dispatch<React.SetStateAction<boolean>>;
   /**
    * Total number of tabs in the nearest parent TabsList.
    * This can be used to determine if the tab is the last one to style it accordingly.
diff --git a/packages/mui-base/src/utils/useCompound.ts b/packages/mui-base/src/utils/useCompound.ts
index c5e4f540c41a66..51f4b997af32d9 100644
--- a/packages/mui-base/src/utils/useCompound.ts
+++ b/packages/mui-base/src/utils/useCompound.ts
@@ -7,9 +7,9 @@ interface RegisterItemReturnValue<Key> {
    */
   id: Key;
   /**
-   * A function that unregisters the item.
+   * A function that deregisters the item.
    */
-  unregister: () => void;
+  deregister: () => void;
 }
 
 export type CompoundComponentContextValue<Key, Subitem> = {
@@ -23,7 +23,6 @@ export type CompoundComponentContextValue<Key, Subitem> = {
    * @param missingKeyGenerator A function that generates a unique id for the item.
    *   It is called with the set of the ids of all the items that have already been registered.
    *   Return `existingKeys.size` if you want to use the index of the new item as the id.
-   * @returns A function that unregisters the item.
    */
   registerItem: (
     id: Key | undefined,
@@ -78,7 +77,7 @@ export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<
   const [subitems, setSubitems] = React.useState(new Map<Key, Subitem>());
   const subitemKeys = React.useRef(new Set<Key>());
 
-  const unregisterItem = React.useCallback(function unregisterItem(id: Key) {
+  const deregisterItem = React.useCallback(function deregisterItem(id: Key) {
     subitemKeys.current.delete(id);
     setSubitems((previousState) => {
       const newState = new Map(previousState);
@@ -115,10 +114,10 @@ export function useCompoundParent<Key, Subitem>(): UseCompoundParentReturnValue<
 
       return {
         id: providedOrGeneratedId,
-        unregister: () => unregisterItem(providedOrGeneratedId),
+        deregister: () => deregisterItem(providedOrGeneratedId),
       };
     },
-    [unregisterItem],
+    [deregisterItem],
   );
 
   const getItemIndex = React.useCallback(
diff --git a/packages/mui-base/src/utils/useCompoundItem.ts b/packages/mui-base/src/utils/useCompoundItem.ts
index 6a19b71de5a45a..62ca5cee0253b9 100644
--- a/packages/mui-base/src/utils/useCompoundItem.ts
+++ b/packages/mui-base/src/utils/useCompoundItem.ts
@@ -50,9 +50,9 @@ export function useCompoundItem<Key, Subitem>(
   const [registeredId, setRegisteredId] = React.useState(id);
 
   useEnhancedEffect(() => {
-    const { id: returnedId, unregister } = registerItem(id, itemMetadata, missingKeyGenerator);
+    const { id: returnedId, deregister } = registerItem(id, itemMetadata, missingKeyGenerator);
     setRegisteredId(returnedId);
-    return unregister;
+    return deregister;
   }, [registerItem, itemMetadata, missingKeyGenerator, id]);
 
   return {
diff --git a/packages/mui-joy/src/List/List.tsx b/packages/mui-joy/src/List/List.tsx
index f54939c984a771..72105c4391c79e 100644
--- a/packages/mui-joy/src/List/List.tsx
+++ b/packages/mui-joy/src/List/List.tsx
@@ -4,8 +4,6 @@ import clsx from 'clsx';
 import { unstable_capitalize as capitalize } from '@mui/utils';
 import { OverridableComponent } from '@mui/types';
 import composeClasses from '@mui/base/composeClasses';
-import { MenuUnstyledContext } from '@mui/base/MenuUnstyled';
-import { SelectUnstyledContext } from '@mui/base/SelectUnstyled';
 import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';
 import { ListProps, ListOwnerState, ListTypeMap } from './ListProps';
@@ -155,8 +153,6 @@ const ListRoot = styled(StyledList, {
  */
 const List = React.forwardRef(function List(inProps, ref) {
   const nesting = React.useContext(NestedListContext);
-  const menuContext = React.useContext(MenuUnstyledContext);
-  const selectContext = React.useContext(SelectUnstyledContext);
   const radioGroupContext = React.useContext(RadioGroupContext);
   const props = useThemeProps<typeof inProps & { component?: React.ElementType }>({
     props: inProps,
@@ -180,9 +176,6 @@ const List = React.forwardRef(function List(inProps, ref) {
   const size = sizeProp || (inProps.size ?? 'md');
 
   let role;
-  if (menuContext || selectContext) {
-    role = 'group';
-  }
   if (radioGroupContext) {
     role = 'presentation';
   }
diff --git a/packages/mui-joy/src/ListItem/ListItem.tsx b/packages/mui-joy/src/ListItem/ListItem.tsx
index 207b2ef793a6a9..1d7b8668dbd11a 100644
--- a/packages/mui-joy/src/ListItem/ListItem.tsx
+++ b/packages/mui-joy/src/ListItem/ListItem.tsx
@@ -7,7 +7,6 @@ import {
 } from '@mui/utils';
 import { OverridableComponent } from '@mui/types';
 import composeClasses from '@mui/base/composeClasses';
-import { MenuUnstyledContext } from '@mui/base/MenuUnstyled';
 import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';
 import useSlot from '../utils/useSlot';
@@ -149,8 +148,6 @@ const ListItem = React.forwardRef(function ListItem(inProps, ref) {
     name: 'JoyListItem',
   });
 
-  const menuContext = React.useContext(MenuUnstyledContext);
-
   const listComponent = React.useContext(ComponentListContext);
   const row = React.useContext(RowListContext);
   const wrap = React.useContext(WrapListContext);
@@ -178,7 +175,7 @@ const ListItem = React.forwardRef(function ListItem(inProps, ref) {
   const component =
     componentProp || (listElement && !listElement.match(/^(ul|ol|menu)$/) ? 'div' : undefined);
 
-  let role = menuContext ? 'none' : undefined;
+  let role;
 
   if (listComponent) {
     // ListItem can be used inside Menu to create nested menus, so it should have role="none"
diff --git a/packages/mui-joy/src/Menu/Menu.tsx b/packages/mui-joy/src/Menu/Menu.tsx
index e9ce966d9df717..4b2a8f3b0cc8c6 100644
--- a/packages/mui-joy/src/Menu/Menu.tsx
+++ b/packages/mui-joy/src/Menu/Menu.tsx
@@ -4,8 +4,7 @@ import { unstable_capitalize as capitalize, HTMLElementType, refType } from '@mu
 import { OverridableComponent } from '@mui/types';
 import composeClasses from '@mui/base/composeClasses';
 import { useSlotProps } from '@mui/base/utils';
-import { MenuUnstyledContext, MenuUnstyledContextType } from '@mui/base/MenuUnstyled';
-import useMenu from '@mui/base/useMenu';
+import useMenu, { MenuProvider } from '@mui/base/useMenu';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { StyledList } from '../List/List';
 import ListProvider, { scopedVariables } from '../List/ListProvider';
@@ -89,9 +88,18 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
   const { getColor } = useColorInversion(variant);
   const color = disablePortal ? getColor(inProps.color, colorProp) : colorProp;
 
+  const handleOpenChange = React.useCallback(
+    (isOpen: boolean) => {
+      if (!isOpen) {
+        onClose?.();
+      }
+    },
+    [onClose],
+  );
+
   const { contextValue, getListboxProps, highlightFirstItem, highlightLastItem } = useMenu({
     open,
-    onClose,
+    onOpenChange: handleOpenChange,
     listboxId: id,
   });
 
@@ -148,17 +156,9 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
     [modifiersProp],
   );
 
-  const menuContextValue: MenuUnstyledContextType = React.useMemo(
-    () => ({
-      ...contextValue,
-      open,
-    }),
-    [contextValue, open],
-  );
-
   const result = (
     <PopperUnstyled {...rootProps} modifiers={modifiers}>
-      <MenuUnstyledContext.Provider value={menuContextValue}>
+      <MenuProvider value={contextValue}>
         <ListProvider nested>
           {disablePortal ? (
             children
@@ -167,7 +167,7 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
             <ColorInversion.Provider value={undefined}>{children}</ColorInversion.Provider>
           )}
         </ListProvider>
-      </MenuUnstyledContext.Provider>
+      </MenuProvider>
     </PopperUnstyled>
   );
 
diff --git a/packages/mui-joy/src/MenuItem/MenuItem.test.js b/packages/mui-joy/src/MenuItem/MenuItem.test.js
index fcc5f4cd0016b9..0611504d83e549 100644
--- a/packages/mui-joy/src/MenuItem/MenuItem.test.js
+++ b/packages/mui-joy/src/MenuItem/MenuItem.test.js
@@ -9,30 +9,28 @@ import {
   screen,
   describeJoyColorInversion,
 } from 'test/utils';
+import { MenuProvider } from '@mui/base/useMenu';
 import { ThemeProvider } from '@mui/joy/styles';
-import { MenuUnstyledContext } from '@mui/base/MenuUnstyled';
 import MenuItem, { menuItemClasses as classes } from '@mui/joy/MenuItem';
 import ListItemButton from '@mui/joy/ListItemButton';
 
 const testContext = {
+  registerItem: () => ({ id: 0, deregister: () => {} }),
+  getItemIndex: () => 0,
+  totalSubitemCount: 1,
+  dispatch: () => {},
   getItemState: () => ({
     disabled: false,
     highlighted: false,
     selected: false,
     index: 0,
   }),
-  getItemProps: () => ({}),
-  registerItem: () => {},
-  unregisterItem: () => {},
-  preregisterItem: () => {},
-  open: false,
   registerHighlightChangeHandler: () => () => {},
+  registerSelectionChangeHandler: () => () => {},
 };
 
 function Wrapper({ children }) {
-  return (
-    <MenuUnstyledContext.Provider value={testContext}>{children}</MenuUnstyledContext.Provider>
-  );
+  return <MenuProvider value={testContext}>{children}</MenuProvider>;
 }
 
 describe('Joy <MenuItem />', () => {
@@ -42,14 +40,9 @@ describe('Joy <MenuItem />', () => {
   describeConformance(<MenuItem />, () => ({
     classes,
     inheritComponent: ListItemButton,
-    render: (node) =>
-      render(
-        <MenuUnstyledContext.Provider value={testContext}>{node}</MenuUnstyledContext.Provider>,
-      ),
+    render: (node) => render(<MenuProvider value={testContext}>{node}</MenuProvider>),
     wrapMount: (mount) => (node) => {
-      const wrapper = mount(
-        <MenuUnstyledContext.Provider value={testContext}>{node}</MenuUnstyledContext.Provider>,
-      );
+      const wrapper = mount(<MenuProvider value={testContext}>{node}</MenuProvider>);
       return wrapper.childAt(0);
     },
     ThemeProvider,
@@ -64,9 +57,7 @@ describe('Joy <MenuItem />', () => {
   describeJoyColorInversion(<MenuItem />, {
     muiName: 'JoyMenuItem',
     classes,
-    wrapper: (node) => (
-      <MenuUnstyledContext.Provider value={testContext}>{node}</MenuUnstyledContext.Provider>
-    ),
+    wrapper: (node) => <MenuProvider value={testContext}>{node}</MenuProvider>,
   });
 
   it('should render with the variant class', () => {
diff --git a/packages/mui-joy/src/MenuList/MenuList.tsx b/packages/mui-joy/src/MenuList/MenuList.tsx
index 711f5f7b6ea3e7..15efab55a95066 100644
--- a/packages/mui-joy/src/MenuList/MenuList.tsx
+++ b/packages/mui-joy/src/MenuList/MenuList.tsx
@@ -4,8 +4,7 @@ import { unstable_capitalize as capitalize } from '@mui/utils';
 import { OverridableComponent } from '@mui/types';
 import composeClasses from '@mui/base/composeClasses';
 import { useSlotProps } from '@mui/base/utils';
-import { MenuUnstyledContext, MenuUnstyledContextType } from '@mui/base/MenuUnstyled';
-import useMenu from '@mui/base/useMenu';
+import useMenu, { MenuProvider, MenuProviderValue } from '@mui/base/useMenu';
 import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';
 import { StyledList } from '../List/List';
@@ -120,15 +119,15 @@ const MenuList = React.forwardRef(function MenuList(inProps, ref) {
         ...contextValue,
         getListboxProps,
         open: true,
-      } as MenuUnstyledContextType),
+      } as MenuProviderValue),
     [contextValue, getListboxProps],
   );
 
   return (
     <MenuListRoot {...listboxProps}>
-      <MenuUnstyledContext.Provider value={menuContextValue}>
+      <MenuProvider value={menuContextValue}>
         <ListProvider nested>{children}</ListProvider>
-      </MenuUnstyledContext.Provider>
+      </MenuProvider>
     </MenuListRoot>
   );
 }) as OverridableComponent<MenuListTypeMap>;
diff --git a/packages/mui-joy/src/Option/Option.tsx b/packages/mui-joy/src/Option/Option.tsx
index 911d59f0c48220..16b1d60ed59dbf 100644
--- a/packages/mui-joy/src/Option/Option.tsx
+++ b/packages/mui-joy/src/Option/Option.tsx
@@ -3,6 +3,7 @@ import PropTypes from 'prop-types';
 import composeClasses from '@mui/base/composeClasses';
 import useOption from '@mui/base/useOption';
 import { useSlotProps } from '@mui/base/utils';
+import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import { StyledListItemButton } from '../ListItemButton/ListItemButton';
 import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';
@@ -60,17 +61,23 @@ const Option = React.forwardRef(function Option(inProps, ref) {
   } = props;
 
   const row = React.useContext(RowListContext);
+  const optionRef = React.useRef<HTMLLIElement>(null);
+  const combinedRef = useForkRef(optionRef, ref);
+
+  const computedLabel =
+    label ?? (typeof children === 'string' ? children : optionRef.current?.innerText);
 
   const { getRootProps, selected, highlighted, index } = useOption({
     disabled,
+    label: computedLabel,
     value,
-    optionRef: ref,
+    optionRef: combinedRef,
   });
 
   const { getColor } = useColorInversion(variant);
   const color = getColor(inProps.color, selected ? 'primary' : colorProp);
 
-  const ownerState = {
+  const ownerState: OptionOwnerState = {
     ...props,
     disabled,
     selected,
diff --git a/packages/mui-joy/src/Option/OptionProps.ts b/packages/mui-joy/src/Option/OptionProps.ts
index d425f84f870437..6b89a7043132de 100644
--- a/packages/mui-joy/src/Option/OptionProps.ts
+++ b/packages/mui-joy/src/Option/OptionProps.ts
@@ -5,7 +5,6 @@ import {
   OverridableTypeMap,
   OverrideProps,
 } from '@mui/types';
-import { ListItemState } from '@mui/base/useList';
 import { ColorPaletteProp, VariantProp, SxProps, ApplyColorInversion } from '../styles/types';
 
 export type OptionSlot = 'root';
@@ -64,9 +63,25 @@ export type OptionProps<
   },
 > = OverrideProps<OptionTypeMap<P, D>, D>;
 
-export interface OptionOwnerState
-  extends ApplyColorInversion<Omit<OptionProps, 'disabled'>>,
-    ListItemState {}
+export interface OptionOwnerState extends ApplyColorInversion<Omit<OptionProps, 'disabled'>> {
+  /**
+   * If `true` the item is disabled.
+   */
+  disabled: boolean;
+  /**
+   * If `true` the item is highlighted.
+   */
+  highlighted: boolean;
+  /**
+   * The 0-based index of the item.
+   */
+  index: number;
+  /**
+   * If `true` the item is selected.
+   */
+  selected: boolean;
+  row: boolean;
+}
 
 export type ExtendOption<M extends OverridableTypeMap> = ((
   props: OverrideProps<ExtendOptionTypeMap<M>, 'a'>,
diff --git a/packages/mui-joy/src/Select/Select.test.tsx b/packages/mui-joy/src/Select/Select.test.tsx
index c0d030a576ac89..bbc06bebc84692 100644
--- a/packages/mui-joy/src/Select/Select.test.tsx
+++ b/packages/mui-joy/src/Select/Select.test.tsx
@@ -612,11 +612,11 @@ describe('Joy <Select />', () => {
 
   it('should show dropdown if the children of the select button is clicked', () => {
     const { getByTestId, getByRole } = render(
-      <Select defaultValue="1">
-        <Option value="1">
-          <span data-testid="test-element" />
-          Eric
-        </Option>
+      <Select
+        defaultValue="1"
+        renderValue={(option) => <span data-testid="test-element">{option?.label}</span>}
+      >
+        <Option value="1">Eric</Option>
       </Select>,
     );
     // Fire Click of the avatar
diff --git a/packages/mui-joy/src/Select/Select.tsx b/packages/mui-joy/src/Select/Select.tsx
index db03f68b4bd49a..f76c0ec389fd08 100644
--- a/packages/mui-joy/src/Select/Select.tsx
+++ b/packages/mui-joy/src/Select/Select.tsx
@@ -11,12 +11,8 @@ import PopperUnstyled, {
   PopperUnstyledProps,
   PopperUnstyledTypeMap,
 } from '@mui/base/PopperUnstyled';
-import {
-  SelectUnstyledContext,
-  flattenOptionGroups,
-  getOptionsFromChildren,
-} from '@mui/base/SelectUnstyled';
-import useSelect, { SelectChild, SelectOption } from '@mui/base/useSelect';
+import useSelect, { SelectProvider } from '@mui/base/useSelect';
+import { SelectOption } from '@mui/base/useOption';
 import composeClasses from '@mui/base/composeClasses';
 import { StyledList } from '../List/List';
 import ListProvider, { scopedVariables } from '../List/ListProvider';
@@ -389,8 +385,6 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
   const renderValue = renderValueProp ?? defaultRenderSingleValue;
   const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
 
-  const [groupedOptions, setGroupedOptions] = React.useState<SelectChild<TValue>[]>([]);
-  const options = React.useMemo(() => flattenOptionGroups(groupedOptions), [groupedOptions]);
   const [listboxOpen, setListboxOpen] = useControlled({
     controlled: listboxOpenProp,
     default: defaultListboxOpen,
@@ -414,10 +408,6 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     [],
   );
 
-  React.useEffect(() => {
-    setGroupedOptions(getOptionsFromChildren(children));
-  }, [children]);
-
   React.useEffect(() => {
     setAnchorEl(rootRef.current);
   }, []);
@@ -446,6 +436,7 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     disabled,
     getButtonProps,
     getListboxProps,
+    getOptionMetadata,
     value,
   } = useSelect({
     buttonRef,
@@ -456,7 +447,6 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     onChange,
     onOpenChange: handleOpenChange,
     open: listboxOpen,
-    options,
     value: valueProp,
   });
 
@@ -476,9 +466,10 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
 
   const classes = useUtilityClasses(ownerState);
 
-  const selectedOption = React.useMemo(() => {
-    return options.find((o) => value === o.value) ?? null;
-  }, [options, value]);
+  const selectedOption = React.useMemo(
+    () => getOptionMetadata(value as TValue) ?? null,
+    [getOptionMetadata, value],
+  );
 
   const [SlotRoot, rootProps] = useSlot('root', {
     ref: handleRef,
@@ -585,16 +576,17 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     result = (
       <SlotListbox
         {...listboxProps}
+        keepMounted
         className={clsx(
           listboxProps.className,
           listboxProps.ownerState?.color === 'context' && selectClasses.colorContext,
         )}
         modifiers={modifiers}
       >
-        <SelectUnstyledContext.Provider value={context}>
+        <SelectProvider value={context}>
           {/* for building grouped options */}
           <ListProvider nested>{children}</ListProvider>
-        </SelectUnstyledContext.Provider>
+        </SelectProvider>
       </SlotListbox>
     );
 
diff --git a/packages/mui-joy/src/Tab/Tab.test.tsx b/packages/mui-joy/src/Tab/Tab.test.tsx
index e99facd354f09d..9a86ca7cebcf96 100644
--- a/packages/mui-joy/src/Tab/Tab.test.tsx
+++ b/packages/mui-joy/src/Tab/Tab.test.tsx
@@ -1,14 +1,27 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { describeConformance, createRenderer, screen, describeJoyColorInversion } from 'test/utils';
-import { TabsContext, TabsUnstyledProps } from '@mui/base/TabsUnstyled';
-import useTabs from '@mui/base/useTabs';
+import { TabsUnstyledProps } from '@mui/base/TabsUnstyled';
+import useTabs, { TabsProvider as BaseTabsProvider } from '@mui/base/useTabs';
+import useTabsList, { TabsListProvider as BaseTabsListProvider } from '@mui/base/useTabsList';
 import { ThemeProvider } from '@mui/joy/styles';
 import Tab, { tabClasses as classes } from '@mui/joy/Tab';
 
+function TabsListProvider({ children }: React.PropsWithChildren<{}>) {
+  const { contextValue: tabsListContextValue } = useTabsList({
+    ref: { current: null },
+  });
+  return <BaseTabsListProvider value={tabsListContextValue}>{children}</BaseTabsListProvider>;
+}
+
 function TabsProvider({ children, ...props }: TabsUnstyledProps) {
-  const { tabsContextValue } = useTabs(props);
-  return <TabsContext.Provider value={tabsContextValue}>{children}</TabsContext.Provider>;
+  const { contextValue: tabsContextValue } = useTabs(props);
+
+  return (
+    <BaseTabsProvider value={tabsContextValue}>
+      <TabsListProvider>{children}</TabsListProvider>
+    </BaseTabsProvider>
+  );
 }
 
 describe('Joy <Tab />', () => {
@@ -58,6 +71,6 @@ describe('Joy <Tab />', () => {
       </TabsProvider>,
     );
     expect(screen.getByRole('tab')).to.have.class(classes.disabled);
-    expect(screen.getByRole('tab')).to.have.attribute('disabled');
+    expect(screen.getByRole('tab')).to.have.attribute('aria-disabled');
   });
 });
diff --git a/packages/mui-joy/src/TabList/TabList.test.tsx b/packages/mui-joy/src/TabList/TabList.test.tsx
index 944fb474dc07a2..beea7ed762993f 100644
--- a/packages/mui-joy/src/TabList/TabList.test.tsx
+++ b/packages/mui-joy/src/TabList/TabList.test.tsx
@@ -1,16 +1,16 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { describeConformance, createRenderer, screen, describeJoyColorInversion } from 'test/utils';
-import { TabsContext, TabsUnstyledProps } from '@mui/base/TabsUnstyled';
-import useTabs from '@mui/base/useTabs';
+import { TabsUnstyledProps } from '@mui/base/TabsUnstyled';
+import useTabs, { TabsProvider as BaseTabsProvider } from '@mui/base/useTabs';
 import { ThemeProvider } from '@mui/joy/styles';
 import Tabs from '@mui/joy/Tabs';
 import TabList, { tabListClasses as classes } from '@mui/joy/TabList';
 import RowListContext from '../List/RowListContext';
 
 function TabsProvider({ children, ...props }: TabsUnstyledProps) {
-  const { tabsContextValue } = useTabs(props);
-  return <TabsContext.Provider value={tabsContextValue}>{children}</TabsContext.Provider>;
+  const { contextValue } = useTabs(props);
+  return <BaseTabsProvider value={contextValue}>{children}</BaseTabsProvider>;
 }
 
 describe('Joy <TabList />', () => {
diff --git a/packages/mui-joy/src/TabPanel/TabPanel.test.tsx b/packages/mui-joy/src/TabPanel/TabPanel.test.tsx
index da7cc2d2ac1ec9..e28bf31140f081 100644
--- a/packages/mui-joy/src/TabPanel/TabPanel.test.tsx
+++ b/packages/mui-joy/src/TabPanel/TabPanel.test.tsx
@@ -1,15 +1,15 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { describeConformance, createRenderer, screen } from 'test/utils';
-import { TabsContext, TabsUnstyledProps } from '@mui/base/TabsUnstyled';
-import useTabs from '@mui/base/useTabs';
+import { TabsUnstyledProps } from '@mui/base/TabsUnstyled';
+import useTabs, { TabsProvider as BaseTabsProvider } from '@mui/base/useTabs';
 import { ThemeProvider } from '@mui/joy/styles';
 import Tabs from '@mui/joy/Tabs';
 import TabPanel, { tabPanelClasses as classes } from '@mui/joy/TabPanel';
 
 function TabsProvider({ children, ...props }: TabsUnstyledProps) {
-  const { tabsContextValue } = useTabs(props);
-  return <TabsContext.Provider value={tabsContextValue}>{children}</TabsContext.Provider>;
+  const { contextValue } = useTabs(props);
+  return <BaseTabsProvider value={contextValue}>{children}</BaseTabsProvider>;
 }
 
 describe('Joy <TabPanel />', () => {
diff --git a/packages/mui-joy/src/TabPanel/TabPanel.tsx b/packages/mui-joy/src/TabPanel/TabPanel.tsx
index 28ff7806d6ff66..928d14ac8be2f4 100644
--- a/packages/mui-joy/src/TabPanel/TabPanel.tsx
+++ b/packages/mui-joy/src/TabPanel/TabPanel.tsx
@@ -3,9 +3,9 @@ import PropTypes from 'prop-types';
 import { unstable_capitalize as capitalize } from '@mui/utils';
 import { unstable_composeClasses as composeClasses } from '@mui/base';
 import { OverridableComponent } from '@mui/types';
-import { useTabContext } from '@mui/base/TabsUnstyled';
 import useTabPanel from '@mui/base/useTabPanel';
 import { useSlotProps } from '@mui/base/utils';
+import { useTabsContext } from '@mui/base/TabsUnstyled';
 import { styled, useThemeProps } from '../styles';
 import SizeTabsContext from '../Tabs/SizeTabsContext';
 import { getTabPanelUtilityClass } from './tabPanelClasses';
@@ -61,7 +61,7 @@ const TabPanel = React.forwardRef(function TabPanel(inProps, ref) {
     name: 'JoyTabPanel',
   });
 
-  const { orientation } = useTabContext() || { orientation: 'horizontal' };
+  const { orientation } = useTabsContext() || { orientation: 'horizontal' };
   const tabsSize = React.useContext(SizeTabsContext);
 
   const { children, value = 0, component, size: sizeProp, ...other } = props;

From b30051a56a3a3fc7f4868a33fc1fc5d5f39271a1 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 3 Apr 2023 21:16:36 +0700
Subject: [PATCH 15/49] joy-ui: add GroupListContext

---
 packages/mui-joy/src/List/GroupListContext.ts |  5 +++++
 packages/mui-joy/src/List/List.tsx            |  5 +++++
 packages/mui-joy/src/ListItem/ListItem.tsx    |  4 +++-
 packages/mui-joy/src/Menu/Menu.tsx            | 19 +++++++++++--------
 packages/mui-joy/src/MenuList/MenuList.tsx    |  5 ++++-
 packages/mui-joy/src/Select/Select.tsx        |  7 +++++--
 6 files changed, 33 insertions(+), 12 deletions(-)
 create mode 100644 packages/mui-joy/src/List/GroupListContext.ts

diff --git a/packages/mui-joy/src/List/GroupListContext.ts b/packages/mui-joy/src/List/GroupListContext.ts
new file mode 100644
index 00000000000000..0f6584855e2355
--- /dev/null
+++ b/packages/mui-joy/src/List/GroupListContext.ts
@@ -0,0 +1,5 @@
+import * as React from 'react';
+
+const GroupListContext = React.createContext<undefined | 'menu' | 'select'>(undefined);
+
+export default GroupListContext;
diff --git a/packages/mui-joy/src/List/List.tsx b/packages/mui-joy/src/List/List.tsx
index 72105c4391c79e..19f99c23679634 100644
--- a/packages/mui-joy/src/List/List.tsx
+++ b/packages/mui-joy/src/List/List.tsx
@@ -10,6 +10,7 @@ import { ListProps, ListOwnerState, ListTypeMap } from './ListProps';
 import { getListUtilityClass } from './listClasses';
 import NestedListContext from './NestedListContext';
 import ComponentListContext from './ComponentListContext';
+import GroupListContext from './GroupListContext';
 import ListProvider from './ListProvider';
 import RadioGroupContext from '../RadioGroup/RadioGroupContext';
 
@@ -153,6 +154,7 @@ const ListRoot = styled(StyledList, {
  */
 const List = React.forwardRef(function List(inProps, ref) {
   const nesting = React.useContext(NestedListContext);
+  const group = React.useContext(GroupListContext);
   const radioGroupContext = React.useContext(RadioGroupContext);
   const props = useThemeProps<typeof inProps & { component?: React.ElementType }>({
     props: inProps,
@@ -176,6 +178,9 @@ const List = React.forwardRef(function List(inProps, ref) {
   const size = sizeProp || (inProps.size ?? 'md');
 
   let role;
+  if (group) {
+    role = 'group';
+  }
   if (radioGroupContext) {
     role = 'presentation';
   }
diff --git a/packages/mui-joy/src/ListItem/ListItem.tsx b/packages/mui-joy/src/ListItem/ListItem.tsx
index 1d7b8668dbd11a..676e1a7660b78a 100644
--- a/packages/mui-joy/src/ListItem/ListItem.tsx
+++ b/packages/mui-joy/src/ListItem/ListItem.tsx
@@ -17,6 +17,7 @@ import RowListContext from '../List/RowListContext';
 import WrapListContext from '../List/WrapListContext';
 import ComponentListContext from '../List/ComponentListContext';
 import ListSubheaderDispatch from '../ListSubheader/ListSubheaderContext';
+import GroupListContext from '../List/GroupListContext';
 
 const useUtilityClasses = (ownerState: ListItemOwnerState) => {
   const { sticky, nested, nesting, variant, color } = ownerState;
@@ -148,6 +149,7 @@ const ListItem = React.forwardRef(function ListItem(inProps, ref) {
     name: 'JoyListItem',
   });
 
+  const group = React.useContext(GroupListContext);
   const listComponent = React.useContext(ComponentListContext);
   const row = React.useContext(RowListContext);
   const wrap = React.useContext(WrapListContext);
@@ -175,7 +177,7 @@ const ListItem = React.forwardRef(function ListItem(inProps, ref) {
   const component =
     componentProp || (listElement && !listElement.match(/^(ul|ol|menu)$/) ? 'div' : undefined);
 
-  let role;
+  let role = group === 'menu' ? 'none' : undefined;
 
   if (listComponent) {
     // ListItem can be used inside Menu to create nested menus, so it should have role="none"
diff --git a/packages/mui-joy/src/Menu/Menu.tsx b/packages/mui-joy/src/Menu/Menu.tsx
index 4b2a8f3b0cc8c6..5e38a71de3d32a 100644
--- a/packages/mui-joy/src/Menu/Menu.tsx
+++ b/packages/mui-joy/src/Menu/Menu.tsx
@@ -8,6 +8,7 @@ import useMenu, { MenuProvider } from '@mui/base/useMenu';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { StyledList } from '../List/List';
 import ListProvider, { scopedVariables } from '../List/ListProvider';
+import GroupListContext from '../List/GroupListContext';
 import { styled, useThemeProps } from '../styles';
 import ColorInversion, { useColorInversion } from '../styles/ColorInversion';
 import { MenuTypeMap, MenuOwnerState } from './MenuProps';
@@ -159,14 +160,16 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
   const result = (
     <PopperUnstyled {...rootProps} modifiers={modifiers}>
       <MenuProvider value={contextValue}>
-        <ListProvider nested>
-          {disablePortal ? (
-            children
-          ) : (
-            // For portal popup, the children should not inherit color inversion from the upper parent.
-            <ColorInversion.Provider value={undefined}>{children}</ColorInversion.Provider>
-          )}
-        </ListProvider>
+        <GroupListContext.Provider value="menu">
+          <ListProvider nested>
+            {disablePortal ? (
+              children
+            ) : (
+              // For portal popup, the children should not inherit color inversion from the upper parent.
+              <ColorInversion.Provider value={undefined}>{children}</ColorInversion.Provider>
+            )}
+          </ListProvider>
+        </GroupListContext.Provider>
       </MenuProvider>
     </PopperUnstyled>
   );
diff --git a/packages/mui-joy/src/MenuList/MenuList.tsx b/packages/mui-joy/src/MenuList/MenuList.tsx
index 15efab55a95066..edb175ad181fb8 100644
--- a/packages/mui-joy/src/MenuList/MenuList.tsx
+++ b/packages/mui-joy/src/MenuList/MenuList.tsx
@@ -9,6 +9,7 @@ import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';
 import { StyledList } from '../List/List';
 import ListProvider, { scopedVariables } from '../List/ListProvider';
+import GroupListContext from '../List/GroupListContext';
 import { MenuListOwnerState, MenuListTypeMap } from './MenuListProps';
 import { getMenuListUtilityClass } from './menuListClasses';
 
@@ -126,7 +127,9 @@ const MenuList = React.forwardRef(function MenuList(inProps, ref) {
   return (
     <MenuListRoot {...listboxProps}>
       <MenuProvider value={menuContextValue}>
-        <ListProvider nested>{children}</ListProvider>
+        <GroupListContext.Provider value="menu">
+          <ListProvider nested>{children}</ListProvider>
+        </GroupListContext.Provider>
       </MenuProvider>
     </MenuListRoot>
   );
diff --git a/packages/mui-joy/src/Select/Select.tsx b/packages/mui-joy/src/Select/Select.tsx
index f76c0ec389fd08..80c8cfe8579ab7 100644
--- a/packages/mui-joy/src/Select/Select.tsx
+++ b/packages/mui-joy/src/Select/Select.tsx
@@ -16,6 +16,7 @@ import { SelectOption } from '@mui/base/useOption';
 import composeClasses from '@mui/base/composeClasses';
 import { StyledList } from '../List/List';
 import ListProvider, { scopedVariables } from '../List/ListProvider';
+import GroupListContext from '../List/GroupListContext';
 import Unfold from '../internal/svg-icons/Unfold';
 import { styled, useThemeProps } from '../styles';
 import ColorInversion, { useColorInversion } from '../styles/ColorInversion';
@@ -584,8 +585,10 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
         modifiers={modifiers}
       >
         <SelectProvider value={context}>
-          {/* for building grouped options */}
-          <ListProvider nested>{children}</ListProvider>
+          <GroupListContext.Provider value="select">
+            {/* for building grouped options */}
+            <ListProvider nested>{children}</ListProvider>
+          </GroupListContext.Provider>
         </SelectProvider>
       </SlotListbox>
     );

From 1a31ee232e7d046e2a01a03a121cb0cab27963a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Mon, 3 Apr 2023 19:51:13 +0200
Subject: [PATCH 16/49] Fix all the tests

---
 .../src/utils/useControllableReducer.test.tsx |  1 -
 packages/mui-material-next/src/Tab/Tab.js     | 18 ++++++++++--
 packages/mui-material-next/src/Tabs/Tabs.js   | 12 ++++----
 .../mui-material-next/src/Tabs/Tabs.test.js   | 15 ++++++----
 .../mui-material-next/src/Tabs/TabsList.js    | 28 +++++++++++--------
 .../src/Tabs/TabsListContext.js               |  5 ++++
 6 files changed, 53 insertions(+), 26 deletions(-)
 create mode 100644 packages/mui-material-next/src/Tabs/TabsListContext.js

diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
index d4d8b4386c509d..f42311863dd1d3 100644
--- a/packages/mui-base/src/utils/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -32,7 +32,6 @@ describe('useControllableReducer', () => {
 
   describe('param: reducer', () => {
     it('calls the provided reducer', () => {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
       const reducer = spy((state: TestState, action: SetStateAction<TestState>) => {
         return {
           ...state,
diff --git a/packages/mui-material-next/src/Tab/Tab.js b/packages/mui-material-next/src/Tab/Tab.js
index 7ec700b8505241..cfbeef0b22bbaa 100644
--- a/packages/mui-material-next/src/Tab/Tab.js
+++ b/packages/mui-material-next/src/Tab/Tab.js
@@ -11,6 +11,7 @@ import {
 } from '@mui/utils';
 import { styled, useThemeProps } from '@mui/material/styles';
 import tabClasses, { getTabUtilityClass } from './tabClasses';
+import TabsListContext from '../Tabs/TabsListContext';
 
 const useUtilityClasses = (ownerState) => {
   const { classes, textColor, fullWidth, wrapped, icon, label, selected, disabled } = ownerState;
@@ -126,14 +127,14 @@ const Tab = React.forwardRef(function Tab(inProps, ref) {
     className,
     disableFocusRipple = false,
     // eslint-disable-next-line react/prop-types
-    fullWidth,
+    fullWidth: fullWidthProp,
     icon: iconProp,
     iconPosition = 'top',
     // eslint-disable-next-line react/prop-types
-    indicator,
+    indicator: indicatorProp,
     label,
     // eslint-disable-next-line react/prop-types
-    textColor = 'inherit',
+    textColor: textColorProp = 'inherit',
     value,
     wrapped = false,
     ...other
@@ -141,6 +142,17 @@ const Tab = React.forwardRef(function Tab(inProps, ref) {
 
   const { disabled, selected, getRootProps } = useTab(props);
 
+  let indicator = indicatorProp;
+  let textColor = textColorProp;
+  let fullWidth = fullWidthProp;
+
+  const tabsListContext = React.useContext(TabsListContext);
+  if (tabsListContext != null) {
+    indicator ??= tabsListContext.indicator;
+    textColor ??= tabsListContext.textColor;
+    fullWidth ??= tabsListContext.fullWidth;
+  }
+
   const ownerState = {
     ...props,
     disabled,
diff --git a/packages/mui-material-next/src/Tabs/Tabs.js b/packages/mui-material-next/src/Tabs/Tabs.js
index b8170544d5628b..1e35183e5b5138 100644
--- a/packages/mui-material-next/src/Tabs/Tabs.js
+++ b/packages/mui-material-next/src/Tabs/Tabs.js
@@ -10,8 +10,7 @@ import {
   unstable_ownerWindow as ownerWindow,
 } from '@mui/utils';
 import { unstable_composeClasses as composeClasses } from '@mui/base';
-import { TabsContext } from '@mui/base/TabsUnstyled';
-import useTabs from '@mui/base/useTabs';
+import useTabs, { TabsProvider } from '@mui/base/useTabs';
 import { styled, useThemeProps, useTheme } from '@mui/material/styles';
 import animate from '@mui/material/internal/animate';
 import TabScrollButton from '../TabScrollButton';
@@ -199,7 +198,10 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
   const clientSize = vertical ? 'clientHeight' : 'clientWidth';
   const size = vertical ? 'height' : 'width';
 
-  const { tabsContextValue } = useTabs({ ...props, direction: theme.direction });
+  const { contextValue: tabsContextValue } = useTabs({
+    ...props,
+    direction: theme.direction ?? 'ltr',
+  });
 
   const ownerState = {
     ...props,
@@ -579,7 +581,7 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
   const conditionalElements = getConditionalElements();
 
   return (
-    <TabsContext.Provider value={tabsContextValue}>
+    <TabsProvider value={tabsContextValue}>
       <TabsRoot
         className={clsx(classes.root, className)}
         ownerState={ownerState}
@@ -618,7 +620,7 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
         </TabsScroller>
         {conditionalElements.scrollButtonEnd}
       </TabsRoot>
-    </TabsContext.Provider>
+    </TabsProvider>
   );
 });
 
diff --git a/packages/mui-material-next/src/Tabs/Tabs.test.js b/packages/mui-material-next/src/Tabs/Tabs.test.js
index 750b97c9af6b41..84989d00e5e914 100644
--- a/packages/mui-material-next/src/Tabs/Tabs.test.js
+++ b/packages/mui-material-next/src/Tabs/Tabs.test.js
@@ -395,7 +395,7 @@ describe('<Tabs />', () => {
     it('when `selectionFollowsFocus` should call if an unselected tab gets focused', () => {
       const handleChange = spy();
       const { getAllByRole } = render(
-        <Tabs value={0} onChange={handleChange} selectionFollowsFocus>
+        <Tabs value={1} onChange={handleChange} selectionFollowsFocus>
           <Tab />
           <Tab />
         </Tabs>,
@@ -406,8 +406,10 @@ describe('<Tabs />', () => {
         lastTab.focus();
       });
 
+      fireEvent.keyDown(lastTab, { key: 'ArrowLeft' });
+
       expect(handleChange.callCount).to.equal(1);
-      expect(handleChange.firstCall.args[1]).to.equal(1);
+      expect(handleChange.firstCall.args[1]).to.equal(0);
     });
 
     it('when `selectionFollowsFocus` should not call if an selected tab gets focused', () => {
@@ -818,10 +820,11 @@ describe('<Tabs />', () => {
     it('should let the selected <Tab /> render the indicator server-side', () => {
       const { container } = renderToString(
         <Tabs value={1}>
-          <Tab />
-          <Tab />
+          <Tab value={0} />
+          <Tab value={1} />
         </Tabs>,
       );
+
       const indicator = container.firstChild.querySelectorAll(`button > .${classes.indicator}`);
       expect(indicator).to.have.lengthOf(1);
     });
@@ -851,7 +854,7 @@ describe('<Tabs />', () => {
                 onChange={handleChange}
                 onKeyDown={handleKeyDown}
                 orientation={orientation}
-                value={1}
+                value={0}
               >
                 <Tab />
                 <Tab />
@@ -1000,7 +1003,7 @@ describe('<Tabs />', () => {
                 onChange={handleChange}
                 onKeyDown={handleKeyDown}
                 orientation={orientation}
-                value={1}
+                value={2}
               >
                 <Tab />
                 <Tab />
diff --git a/packages/mui-material-next/src/Tabs/TabsList.js b/packages/mui-material-next/src/Tabs/TabsList.js
index 0964bac4d912a9..ceb35eb1f1a614 100644
--- a/packages/mui-material-next/src/Tabs/TabsList.js
+++ b/packages/mui-material-next/src/Tabs/TabsList.js
@@ -1,7 +1,8 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import { styled } from '@mui/material/styles';
-import useTabsList from '@mui/base/useTabsList';
+import useTabsList, { TabsListProvider } from '@mui/base/useTabsList';
+import TabsListContext from './TabsListContext';
 
 const FlexContainer = styled('div', {
   name: 'MuiTabs',
@@ -28,27 +29,32 @@ const FlexContainer = styled('div', {
  * @ignore - internal component.
  */
 const TabsList = React.forwardRef((props, ref) => {
-  const { variant, indicator, textColor, ...other } = props;
+  const { variant, indicator, textColor, children, ...other } = props;
 
-  const { getRootProps, processChildren } = useTabsList({ ...props, ref });
+  const { getRootProps, contextValue } = useTabsList({ ...props, ref });
 
-  const processedChildren = processChildren();
-  const children = React.Children.map(processedChildren, (child) => {
-    return React.cloneElement(child, {
+  const tabsListContextValue = React.useMemo(
+    () => ({
       indicator,
       textColor,
       fullWidth: variant === 'fullWidth',
-    });
-  });
+    }),
+    [indicator, textColor, variant],
+  );
 
   return (
-    <FlexContainer {...other} {...getRootProps()}>
-      {children}
-    </FlexContainer>
+    <TabsListProvider value={contextValue}>
+      <TabsListContext.Provider value={tabsListContextValue}>
+        <FlexContainer {...other} {...getRootProps()}>
+          {children}
+        </FlexContainer>
+      </TabsListContext.Provider>
+    </TabsListProvider>
   );
 });
 
 TabsList.propTypes = {
+  children: PropTypes.node,
   indicator: PropTypes.node,
   textColor: PropTypes.oneOf(['primary', 'secondary']),
   variant: PropTypes.oneOf(['fullWidth', 'scrollable', 'standard']),
diff --git a/packages/mui-material-next/src/Tabs/TabsListContext.js b/packages/mui-material-next/src/Tabs/TabsListContext.js
new file mode 100644
index 00000000000000..8230cb50b80e39
--- /dev/null
+++ b/packages/mui-material-next/src/Tabs/TabsListContext.js
@@ -0,0 +1,5 @@
+import * as React from 'react';
+
+const TabsListContext = React.createContext(null);
+
+export default TabsListContext;

From cb3742f2f8f98cec0ad883880ed81c1f3b1a72e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Mon, 3 Apr 2023 20:01:44 +0200
Subject: [PATCH 17/49] Docs and demos

---
 docs/data/base/components/menu/MenuSimple.js  |  6 +++-
 docs/data/base/components/menu/MenuSimple.tsx |  6 +++-
 .../menu/UnstyledMenuIntroduction.js          |  6 +++-
 .../menu/UnstyledMenuIntroduction.tsx         |  6 +++-
 docs/data/base/components/menu/UseMenu.js     | 23 ++++++++-------
 docs/data/base/components/menu/UseMenu.tsx    | 28 ++++++++-----------
 .../base/components/menu/WrappedMenuItems.js  |  6 +++-
 .../base/components/menu/WrappedMenuItems.tsx |  6 +++-
 .../select/UnstyledSelectCustomRenderValue.js |  2 +-
 .../UnstyledSelectCustomRenderValue.tsx       |  2 +-
 .../select/UnstyledSelectObjectValuesForm.tsx |  2 +-
 docs/pages/base/api/use-option.json           |  7 +++++
 docs/pages/base/api/use-tab.json              |  8 ++++++
 .../api-docs/use-menu/use-menu.json           |  5 ++--
 .../api-docs/use-tab/use-tab.json             |  2 ++
 15 files changed, 76 insertions(+), 39 deletions(-)

diff --git a/docs/data/base/components/menu/MenuSimple.js b/docs/data/base/components/menu/MenuSimple.js
index e30162faa5bac8..c371bcc9349d52 100644
--- a/docs/data/base/components/menu/MenuSimple.js
+++ b/docs/data/base/components/menu/MenuSimple.js
@@ -75,7 +75,11 @@ export default function UnstyledMenuSimple() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/menu/MenuSimple.tsx b/docs/data/base/components/menu/MenuSimple.tsx
index 7a789d99f19566..fc27eb7c719038 100644
--- a/docs/data/base/components/menu/MenuSimple.tsx
+++ b/docs/data/base/components/menu/MenuSimple.tsx
@@ -75,7 +75,11 @@ export default function UnstyledMenuSimple() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/menu/UnstyledMenuIntroduction.js b/docs/data/base/components/menu/UnstyledMenuIntroduction.js
index 043292c0d81257..390c6a74a5856e 100644
--- a/docs/data/base/components/menu/UnstyledMenuIntroduction.js
+++ b/docs/data/base/components/menu/UnstyledMenuIntroduction.js
@@ -58,7 +58,11 @@ export default function UnstyledMenuIntroduction() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx b/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
index 2549b14717ab1a..b00d854c514622 100644
--- a/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
+++ b/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
@@ -58,7 +58,11 @@ export default function UnstyledMenuIntroduction() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/menu/UseMenu.js b/docs/data/base/components/menu/UseMenu.js
index 7ff446f26e3467..dc1e408f4712f6 100644
--- a/docs/data/base/components/menu/UseMenu.js
+++ b/docs/data/base/components/menu/UseMenu.js
@@ -1,18 +1,17 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { MenuUnstyledContext } from '@mui/base/MenuUnstyled';
-import useMenu from '@mui/base/useMenu';
+import useMenu, { MenuProvider } from '@mui/base/useMenu';
 import useMenuItem from '@mui/base/useMenuItem';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { GlobalStyles } from '@mui/system';
 import clsx from 'clsx';
 
 const Menu = React.forwardRef(function Menu(props, ref) {
-  const { children, onClose, open, ...other } = props;
+  const { children, onOpenChange, open, ...other } = props;
 
   const { contextValue, getListboxProps } = useMenu({
     listboxRef: ref,
-    onClose,
+    onOpenChange,
     open,
   });
 
@@ -26,16 +25,14 @@ const Menu = React.forwardRef(function Menu(props, ref) {
 
   return (
     <ul className="menu-root" {...other} {...getListboxProps()}>
-      <MenuUnstyledContext.Provider value={menuContextValue}>
-        {children}
-      </MenuUnstyledContext.Provider>
+      <MenuProvider value={menuContextValue}>{children}</MenuProvider>
     </ul>
   );
 });
 
 Menu.propTypes = {
   children: PropTypes.node,
-  onClose: PropTypes.func.isRequired,
+  onOpenChange: PropTypes.func.isRequired,
   open: PropTypes.bool.isRequired,
 };
 
@@ -76,9 +73,11 @@ export default function UseMenu() {
     setAnchorEl(anchorEl ? null : event.currentTarget);
   };
 
-  const handleOnClose = () => {
-    setAnchorEl(null);
-    buttonRef.current.focus();
+  const handleOpenChange = (isOpen) => {
+    if (!isOpen) {
+      setAnchorEl(null);
+      buttonRef.current.focus();
+    }
   };
 
   const open = Boolean(anchorEl);
@@ -104,7 +103,7 @@ export default function UseMenu() {
         Commands
       </button>
       <PopperUnstyled open={open} anchorEl={anchorEl}>
-        <Menu onClose={handleOnClose} open={open}>
+        <Menu onOpenChange={handleOpenChange} open={open}>
           <MenuItem>Cut</MenuItem>
           <MenuItem>Copy</MenuItem>
           <MenuItem>Paste</MenuItem>
diff --git a/docs/data/base/components/menu/UseMenu.tsx b/docs/data/base/components/menu/UseMenu.tsx
index 4c3a1b3bbed2c5..75f0e4dbe8bc83 100644
--- a/docs/data/base/components/menu/UseMenu.tsx
+++ b/docs/data/base/components/menu/UseMenu.tsx
@@ -1,9 +1,5 @@
 import * as React from 'react';
-import {
-  MenuUnstyledContext,
-  MenuUnstyledContextType,
-} from '@mui/base/MenuUnstyled';
-import useMenu from '@mui/base/useMenu';
+import useMenu, { MenuProvider, MenuProviderValue } from '@mui/base/useMenu';
 import useMenuItem from '@mui/base/useMenuItem';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { GlobalStyles } from '@mui/system';
@@ -11,20 +7,20 @@ import clsx from 'clsx';
 
 const Menu = React.forwardRef(function Menu(
   props: React.ComponentPropsWithoutRef<'ul'> & {
-    onClose: () => void;
+    onOpenChange: (isOpen: boolean) => void;
     open: boolean;
   },
   ref: React.Ref<HTMLUListElement>,
 ) {
-  const { children, onClose, open, ...other } = props;
+  const { children, onOpenChange, open, ...other } = props;
 
   const { contextValue, getListboxProps } = useMenu({
     listboxRef: ref,
-    onClose,
+    onOpenChange,
     open,
   });
 
-  const menuContextValue: MenuUnstyledContextType = React.useMemo(
+  const menuContextValue: MenuProviderValue = React.useMemo(
     () => ({
       ...contextValue,
       open: true,
@@ -34,9 +30,7 @@ const Menu = React.forwardRef(function Menu(
 
   return (
     <ul className="menu-root" {...other} {...getListboxProps()}>
-      <MenuUnstyledContext.Provider value={menuContextValue}>
-        {children}
-      </MenuUnstyledContext.Provider>
+      <MenuProvider value={menuContextValue}>{children}</MenuProvider>
     </ul>
   );
 });
@@ -77,9 +71,11 @@ export default function UseMenu() {
     setAnchorEl(anchorEl ? null : event.currentTarget);
   };
 
-  const handleOnClose = () => {
-    setAnchorEl(null);
-    buttonRef.current!.focus();
+  const handleOpenChange = (isOpen: boolean) => {
+    if (!isOpen) {
+      setAnchorEl(null);
+      buttonRef.current!.focus();
+    }
   };
 
   const open = Boolean(anchorEl);
@@ -105,7 +101,7 @@ export default function UseMenu() {
         Commands
       </button>
       <PopperUnstyled open={open} anchorEl={anchorEl}>
-        <Menu onClose={handleOnClose} open={open}>
+        <Menu onOpenChange={handleOpenChange} open={open}>
           <MenuItem>Cut</MenuItem>
           <MenuItem>Copy</MenuItem>
           <MenuItem>Paste</MenuItem>
diff --git a/docs/data/base/components/menu/WrappedMenuItems.js b/docs/data/base/components/menu/WrappedMenuItems.js
index e2084c826d3629..5df545f0af4b82 100644
--- a/docs/data/base/components/menu/WrappedMenuItems.js
+++ b/docs/data/base/components/menu/WrappedMenuItems.js
@@ -90,7 +90,11 @@ export default function WrappedMenuItems() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/menu/WrappedMenuItems.tsx b/docs/data/base/components/menu/WrappedMenuItems.tsx
index 7ad2b1fdde6b88..dd7d7362ac912f 100644
--- a/docs/data/base/components/menu/WrappedMenuItems.tsx
+++ b/docs/data/base/components/menu/WrappedMenuItems.tsx
@@ -84,7 +84,11 @@ export default function WrappedMenuItems() {
       <MenuUnstyled
         actions={menuActions}
         open={isOpen}
-        onClose={close}
+        onOpenChange={(open) => {
+          if (!open) {
+            close();
+          }
+        }}
         anchorEl={anchorEl}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
diff --git a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
index 81ec6bd3813ece..5678659442536f 100644
--- a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
+++ b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import SelectUnstyled, { selectUnstyledClasses } from '@mui/base/SelectUnstyled';
-
 import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
+
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
 
diff --git a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
index fcb0cc3a099d56..de63a1223f98dc 100644
--- a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
+++ b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
@@ -3,8 +3,8 @@ import SelectUnstyled, {
   SelectUnstyledProps,
   selectUnstyledClasses,
 } from '@mui/base/SelectUnstyled';
-import { SelectOption } from '@mui/base/useSelect';
 import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
+import { SelectOption } from '@mui/base/useOption';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
 
diff --git a/docs/data/base/components/select/UnstyledSelectObjectValuesForm.tsx b/docs/data/base/components/select/UnstyledSelectObjectValuesForm.tsx
index 4b0aafb658d28e..c2e3531a9adb49 100644
--- a/docs/data/base/components/select/UnstyledSelectObjectValuesForm.tsx
+++ b/docs/data/base/components/select/UnstyledSelectObjectValuesForm.tsx
@@ -3,7 +3,7 @@ import SelectUnstyled, {
   SelectUnstyledProps,
   selectUnstyledClasses,
 } from '@mui/base/SelectUnstyled';
-import { SelectOption } from '@mui/base/useSelect';
+import { SelectOption } from '@mui/base/useOption';
 import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
diff --git a/docs/pages/base/api/use-option.json b/docs/pages/base/api/use-option.json
index a9c89561e50f0e..2c70333285a5e9 100644
--- a/docs/pages/base/api/use-option.json
+++ b/docs/pages/base/api/use-option.json
@@ -24,6 +24,13 @@
     },
     "highlighted": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "index": { "type": { "name": "number", "description": "number" }, "required": true },
+    "ref": {
+      "type": {
+        "name": "React.RefCallback&lt;HTMLElement&gt;",
+        "description": "React.RefCallback&lt;HTMLElement&gt;"
+      },
+      "required": true
+    },
     "selected": { "type": { "name": "boolean", "description": "boolean" }, "required": true }
   },
   "name": "useOption",
diff --git a/docs/pages/base/api/use-tab.json b/docs/pages/base/api/use-tab.json
index a34bb3ba596c21..ebde246f70023f 100644
--- a/docs/pages/base/api/use-tab.json
+++ b/docs/pages/base/api/use-tab.json
@@ -7,6 +7,7 @@
   },
   "returnValue": {
     "active": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "focusVisible": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "getRootProps": {
       "type": {
         "name": "&lt;TOther extends Record&lt;string, any&gt; = {}&gt;(externalProps?: TOther) =&gt; UseTabRootSlotProps&lt;TOther&gt;",
@@ -17,6 +18,13 @@
     "highlighted": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "index": { "type": { "name": "number", "description": "number" }, "required": true },
     "selected": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "setFocusVisible": {
+      "type": {
+        "name": "React.Dispatch&lt;React.SetStateAction&lt;boolean&gt;&gt;",
+        "description": "React.Dispatch&lt;React.SetStateAction&lt;boolean&gt;&gt;"
+      },
+      "required": true
+    },
     "totalTabsCount": { "type": { "name": "number", "description": "number" }, "required": true }
   },
   "name": "useTab",
diff --git a/docs/translations/api-docs/use-menu/use-menu.json b/docs/translations/api-docs/use-menu/use-menu.json
index 4dbb8515560912..fb50e975089198 100644
--- a/docs/translations/api-docs/use-menu/use-menu.json
+++ b/docs/translations/api-docs/use-menu/use-menu.json
@@ -2,11 +2,12 @@
   "hookDescription": "",
   "parametersDescriptions": {},
   "returnValueDescriptions": {
-    "contextValue": "The value for the menu context.",
+    "contextValue": "The value to be passed into the MenuProvider.",
     "getListboxProps": "Resolver for the listbox component's props.",
     "highlightedOption": "The highlighted option in the menu listbox.",
     "highlightFirstItem": "Callback for highlighting the first item in the menu listbox.",
     "highlightLastItem": "Callback for highlighting the last item in the menu listbox.",
-    "menuItems": "Items in the menu listbox."
+    "menuItems": "Items in the menu listbox.",
+    "open": "If <code>true</code>, the menu is open."
   }
 }
diff --git a/docs/translations/api-docs/use-tab/use-tab.json b/docs/translations/api-docs/use-tab/use-tab.json
index e45aaf2dbd40dd..65c3f019762137 100644
--- a/docs/translations/api-docs/use-tab/use-tab.json
+++ b/docs/translations/api-docs/use-tab/use-tab.json
@@ -8,10 +8,12 @@
   },
   "returnValueDescriptions": {
     "active": "If <code>true</code>, the tab is active (as in </code>:active</code> pseudo-class; in other words, pressed).",
+    "focusVisible": "If <code>true</code>, the tab has visible focus.\nThis is a workaround for browsers that do not support this feature natively.",
     "getRootProps": "Resolver for the root slot's props.",
     "highlighted": "If <code>true</code>, the tab is highlighted.",
     "index": "0-based index of the tab in the list of tabs.",
     "selected": "If <code>true</code>, the tab is selected.",
+    "setFocusVisible": "Sets the focus-visible state of the tab.\nThis is a workaround for browsers that do not support this feature natively.",
     "totalTabsCount": "Total number of tabs in the nearest parent TabsList.\nThis can be used to determine if the tab is the last one to style it accordingly."
   }
 }

From 78be65719f60eefa220e4c03fb3e8a4b6452a454 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Mon, 3 Apr 2023 20:23:10 +0200
Subject: [PATCH 18/49] Include inaccessible elements in tests

---
 packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx | 2 +-
 packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index 0036d431dc27fe..08d79c413208e8 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -356,7 +356,7 @@ describe('<SelectUnstyled />', () => {
 
       expect(select).to.have.attribute('aria-expanded', 'false');
       expect(select).to.have.text('1');
-      expect(queryByRole('listbox')).not.toBeVisible();
+      expect(queryByRole('listbox', { hidden: true })).not.toBeVisible();
     });
   });
 
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
index 3187eb21f0e765..380b5744f452bf 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.test.tsx
@@ -123,7 +123,7 @@ describe('<TabsUnstyled />', () => {
       );
 
       const tabs = getAllByRole('tab');
-      const tabPanels = getAllByRole('tabpanel');
+      const tabPanels = getAllByRole('tabpanel', { hidden: true });
 
       expect(tabPanels[0]).to.have.attribute('aria-labelledby', tabs[1].id);
       expect(tabPanels[1]).to.have.attribute('aria-labelledby', tabs[0].id);
@@ -148,7 +148,7 @@ describe('<TabsUnstyled />', () => {
       );
 
       const tabs = getAllByRole('tab');
-      const tabPanels = getAllByRole('tabpanel');
+      const tabPanels = getAllByRole('tabpanel', { hidden: true });
 
       expect(tabs[0]).to.have.attribute('aria-controls', tabPanels[1].id);
       expect(tabs[1]).to.have.attribute('aria-controls', tabPanels[0].id);

From af31a7f96d69799d4e2c424456fd9d818ea7bc11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 10:02:14 +0200
Subject: [PATCH 19/49] Name the TabsListUnstyled function

---
 packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
index cc6a2aee5c4b11..36061335060123 100644
--- a/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
+++ b/packages/mui-base/src/TabsListUnstyled/TabsListUnstyled.tsx
@@ -33,7 +33,10 @@ const useUtilityClasses = (ownerState: { orientation: 'horizontal' | 'vertical'
  *
  * - [TabsListUnstyled API](https://mui.com/base/react-tabs/components-api/#tabs-list-unstyled)
  */
-const TabsListUnstyled = React.forwardRef<unknown, TabsListUnstyledProps>((props, ref) => {
+const TabsListUnstyled = React.forwardRef<unknown, TabsListUnstyledProps>(function TabsListUnstyled(
+  props,
+  ref,
+) {
   const { children, component, slotProps = {}, slots = {}, ...other } = props;
 
   const { isRtl, orientation, getRootProps, contextValue } = useTabsList({

From 35ca76fe4a0fca1da0969b4d7d8a7f5c11f0afed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 11:05:22 +0200
Subject: [PATCH 20/49] Remove controlled open prop from Select implementations

---
 .../src/SelectUnstyled/SelectUnstyled.tsx     | 30 +++++--------------
 packages/mui-base/src/useSelect/useSelect.ts  |  3 +-
 .../mui-base/src/useSelect/useSelect.types.ts |  1 +
 .../src/utils/useControllableReducer.ts       | 19 +++++-------
 packages/mui-joy/src/Select/Select.tsx        | 20 ++++---------
 5 files changed, 23 insertions(+), 50 deletions(-)

diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
index 6913f36a966686..f593e9a0da6bfc 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
@@ -1,9 +1,6 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import {
-  unstable_useForkRef as useForkRef,
-  unstable_useControlled as useControlled,
-} from '@mui/utils';
+import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import {
   SelectUnstyledListboxSlotProps,
   SelectUnstyledOwnerState,
@@ -123,13 +120,6 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
   const renderValue: (option: SelectValue<SelectOption<TValue>, Multiple>) => React.ReactNode =
     renderValueProp ?? defaultRenderValue;
 
-  const [listboxOpen, setListboxOpen] = useControlled({
-    controlled: listboxOpenProp,
-    default: defaultListboxOpen,
-    name: 'SelectUnstyled',
-    state: 'listboxOpen',
-  });
-
   const [buttonDefined, setButtonDefined] = React.useState(false);
   const buttonRef = React.useRef<HTMLElement | null>(null);
   const listboxRef = React.useRef<HTMLElement>(null);
@@ -150,14 +140,6 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     }
   }, [autoFocus]);
 
-  const handleOpenChange = React.useCallback(
-    (isOpen: boolean) => {
-      setListboxOpen(isOpen);
-      onListboxOpenChange?.(isOpen);
-    },
-    [setListboxOpen, onListboxOpenChange],
-  );
-
   const {
     buttonActive,
     buttonFocusVisible,
@@ -167,15 +149,17 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     getListboxProps,
     getOptionMetadata,
     value,
+    open,
   } = useSelect({
     buttonRef: handleButtonRef,
+    defaultOpen: defaultListboxOpen,
     defaultValue,
     disabled: disabledProp,
     listboxId,
     multiple,
-    open: listboxOpen,
+    open: listboxOpenProp,
     onChange,
-    onOpenChange: handleOpenChange,
+    onOpenChange: onListboxOpenChange,
     optionStringifier,
     value: valueProp,
   });
@@ -186,7 +170,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     defaultListboxOpen,
     disabled,
     focusVisible: buttonFocusVisible,
-    open: listboxOpen,
+    open,
     multiple,
     renderValue,
     value,
@@ -222,7 +206,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     additionalProps: {
       anchorEl: buttonRef.current,
       keepMounted: true,
-      open: listboxOpen,
+      open,
       placement: 'bottom-start' as const,
       role: undefined,
     },
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 7475501ee372b2..480a3900366c8d 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -44,6 +44,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
 ): UseSelectResult<TValue, Multiple> {
   const {
     buttonRef: buttonRefProp,
+    defaultOpen = false,
     defaultValue: defaultValueProp,
     disabled = false,
     listboxId: listboxIdProp,
@@ -274,7 +275,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
     getInitialState: () => ({
       highlightedValue: null,
       selectedValues: defaultValue ?? [],
-      open: false,
+      open: defaultOpen,
     }),
     getItemId: (itemValue) => options.get(itemValue)?.id,
     controlledProps: controlledState,
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 53ddee3ff81f5c..6a349525fae473 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -20,6 +20,7 @@ export interface SelectOptionDefinition<Value> {
 }
 
 export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
+  defaultOpen?: boolean;
   defaultValue?: SelectValue<TValue, Multiple>;
   disabled?: boolean;
   buttonRef?: React.Ref<Element>;
diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
index 4ba2ae8c5ddc87..5257c4645990c9 100644
--- a/packages/mui-base/src/utils/useControllableReducer.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -41,12 +41,14 @@ function getControlledState<State>(internalState: State, controlledProps: Partia
  */
 function useStateChangeDetection<State extends {}>(
   nextState: State,
-  internalPreviousState: State,
+  initialState: State,
   stateComparers: StateComparers<State>,
   onStateChange: StateChangeCallback<State>,
   controlledProps: Partial<State>,
   lastActionRef: React.MutableRefObject<ControllableReducerAction | null>,
 ) {
+  const internalPreviousStateRef = React.useRef<State>(initialState);
+
   React.useEffect(() => {
     if (lastActionRef.current === null) {
       // Detect changes only if an action has been dispatched.
@@ -58,7 +60,7 @@ function useStateChangeDetection<State extends {}>(
       return;
     }
 
-    const previousState = getControlledState(internalPreviousState, controlledProps);
+    const previousState = getControlledState(internalPreviousStateRef.current, controlledProps);
 
     (Object.keys(nextState) as (keyof State)[]).forEach((key) => {
       // go through all state keys and compare them with the previous state
@@ -78,9 +80,10 @@ function useStateChangeDetection<State extends {}>(
       }
     });
 
+    internalPreviousStateRef.current = nextState;
     lastActionRef.current = null;
   }, [
-    internalPreviousState,
+    internalPreviousStateRef,
     nextState,
     lastActionRef,
     onStateChange,
@@ -129,6 +132,7 @@ export default function useControllableReducer<
   // The reducer that is passed to React.useReducer is wrapped with a function that augments the state with controlled values.
   const reducerWithControlledState = React.useCallback(
     (state: State, action: Action & ActionAddOn) => {
+      actionRef.current = action;
       const controlledState = getControlledState(state, controlledProps);
       return reducer(controlledState, action);
     },
@@ -140,7 +144,6 @@ export default function useControllableReducer<
   // The action that is passed to dispatch is augmented with the actionAddOn.
   const dispatchWithAddOn = React.useCallback(
     (action: Action) => {
-      actionRef.current = action;
       dispatch({
         ...action,
         ...actionAddOn,
@@ -149,15 +152,9 @@ export default function useControllableReducer<
     [actionAddOn],
   );
 
-  const previousState = React.useRef<State>(initialState);
-
-  React.useEffect(() => {
-    previousState.current = nextState;
-  }, [nextState]);
-
   useStateChangeDetection<State>(
     nextState,
-    previousState.current,
+    initialState,
     stateComparers ?? EMPTY_OBJECT,
     onStateChange ?? NOOP,
     controlledProps,
diff --git a/packages/mui-joy/src/Select/Select.tsx b/packages/mui-joy/src/Select/Select.tsx
index 80c8cfe8579ab7..6cc916d5480270 100644
--- a/packages/mui-joy/src/Select/Select.tsx
+++ b/packages/mui-joy/src/Select/Select.tsx
@@ -2,11 +2,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import clsx from 'clsx';
 import { OverridableComponent, OverrideProps, DefaultComponentProps } from '@mui/types';
-import {
-  unstable_capitalize as capitalize,
-  unstable_useForkRef as useForkRef,
-  unstable_useControlled as useControlled,
-} from '@mui/utils';
+import { unstable_capitalize as capitalize, unstable_useForkRef as useForkRef } from '@mui/utils';
 import PopperUnstyled, {
   PopperUnstyledProps,
   PopperUnstyledTypeMap,
@@ -386,13 +382,6 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
   const renderValue = renderValueProp ?? defaultRenderSingleValue;
   const [anchorEl, setAnchorEl] = React.useState<HTMLElement | null>(null);
 
-  const [listboxOpen, setListboxOpen] = useControlled({
-    controlled: listboxOpenProp,
-    default: defaultListboxOpen,
-    name: 'SelectUnstyled',
-    state: 'listboxOpen',
-  });
-
   const rootRef = React.useRef<HTMLElement | null>(null);
   const buttonRef = React.useRef<HTMLElement | null>(null);
   const listboxRef = React.useRef<HTMLElement | null>(null);
@@ -421,13 +410,12 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
 
   const handleOpenChange = React.useCallback(
     (isOpen: boolean) => {
-      setListboxOpen(isOpen);
       onListboxOpenChange?.(isOpen);
       if (!isOpen) {
         onClose?.();
       }
     },
-    [onClose, onListboxOpenChange, setListboxOpen],
+    [onClose, onListboxOpenChange],
   );
 
   const {
@@ -438,16 +426,18 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     getButtonProps,
     getListboxProps,
     getOptionMetadata,
+    open: listboxOpen,
     value,
   } = useSelect({
     buttonRef,
+    defaultOpen: defaultListboxOpen,
     defaultValue,
     disabled: disabledProp,
     listboxId,
     multiple: false,
     onChange,
     onOpenChange: handleOpenChange,
-    open: listboxOpen,
+    open: listboxOpenProp,
     value: valueProp,
   });
 

From 5ddbe6f52cf6a5a58d92baa40ecda34ed445475a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 11:16:01 +0200
Subject: [PATCH 21/49] Make Joy's Option value mandatory

---
 docs/pages/joy-ui/api/option.json                               | 2 +-
 packages/mui-joy/src/Option/Option.tsx                          | 2 +-
 packages/mui-joy/src/Option/OptionProps.ts                      | 2 +-
 .../regressions/fixtures/JoyColorInversion/JoyColorInversion.js | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/pages/joy-ui/api/option.json b/docs/pages/joy-ui/api/option.json
index 3cba2666645dd4..48d16c0eaad80f 100644
--- a/docs/pages/joy-ui/api/option.json
+++ b/docs/pages/joy-ui/api/option.json
@@ -1,5 +1,6 @@
 {
   "props": {
+    "value": { "type": { "name": "any" }, "required": true },
     "children": { "type": { "name": "node" } },
     "color": {
       "type": {
@@ -17,7 +18,6 @@
         "description": "Array&lt;func<br>&#124;&nbsp;object<br>&#124;&nbsp;bool&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object"
       }
     },
-    "value": { "type": { "name": "any" } },
     "variant": {
       "type": {
         "name": "union",
diff --git a/packages/mui-joy/src/Option/Option.tsx b/packages/mui-joy/src/Option/Option.tsx
index 16b1d60ed59dbf..64f75b10646e51 100644
--- a/packages/mui-joy/src/Option/Option.tsx
+++ b/packages/mui-joy/src/Option/Option.tsx
@@ -149,7 +149,7 @@ Option.propTypes /* remove-proptypes */ = {
   /**
    * The option value.
    */
-  value: PropTypes.any,
+  value: PropTypes.any.isRequired,
   /**
    * The [global variant](https://mui.com/joy-ui/main-features/global-variants/) to use.
    * @default 'plain'
diff --git a/packages/mui-joy/src/Option/OptionProps.ts b/packages/mui-joy/src/Option/OptionProps.ts
index 6b89a7043132de..5d1ab7d1b235be 100644
--- a/packages/mui-joy/src/Option/OptionProps.ts
+++ b/packages/mui-joy/src/Option/OptionProps.ts
@@ -42,7 +42,7 @@ export interface OptionTypeMap<P = {}, D extends React.ElementType = 'li'> {
     /**
      * The option value.
      */
-    value?: any;
+    value: any;
     /**
      * The system prop that allows defining system overrides as well as additional CSS styles.
      */
diff --git a/test/regressions/fixtures/JoyColorInversion/JoyColorInversion.js b/test/regressions/fixtures/JoyColorInversion/JoyColorInversion.js
index b00b0c70ec44ff..0be461f1fd3d8f 100644
--- a/test/regressions/fixtures/JoyColorInversion/JoyColorInversion.js
+++ b/test/regressions/fixtures/JoyColorInversion/JoyColorInversion.js
@@ -104,7 +104,7 @@ export default function JoyColorInversion() {
       {renderComponents(<ListSubheader>Subheader</ListSubheader>)}
       {renderComponents(
         <Select placeholder="Choose one">
-          <Option>Option</Option>
+          <Option value={0}>Option</Option>
         </Select>,
       )}
       {renderComponents(<Radio label="Label" />)}

From 23fb884bdc899835be71869ec37273d7ec0c300e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 12:35:35 +0200
Subject: [PATCH 22/49] Update Joy Select demo to restore the previous look

---
 .../components/select/SelectCustomOption.js   | 53 +++++++++++-------
 .../components/select/SelectCustomOption.tsx  | 55 ++++++++++++-------
 2 files changed, 67 insertions(+), 41 deletions(-)

diff --git a/docs/data/joy/components/select/SelectCustomOption.js b/docs/data/joy/components/select/SelectCustomOption.js
index d76aa7a3e3b8b3..2b875476bde0d9 100644
--- a/docs/data/joy/components/select/SelectCustomOption.js
+++ b/docs/data/joy/components/select/SelectCustomOption.js
@@ -5,6 +5,27 @@ import ListDivider from '@mui/joy/ListDivider';
 import Select from '@mui/joy/Select';
 import Option from '@mui/joy/Option';
 
+const options = [
+  { value: '1', label: 'Eric', src: '/static/images/avatar/1.jpg' },
+  { value: '2', label: 'Smith', src: '/static/images/avatar/2.jpg' },
+  { value: '3', label: 'Erika', src: '/static/images/avatar/3.jpg' },
+];
+
+function renderValue(option) {
+  if (!option) {
+    return null;
+  }
+
+  return (
+    <React.Fragment>
+      <ListItemDecorator>
+        <Avatar size="sm" src={options.find((o) => o.value === option.value)?.src} />
+      </ListItemDecorator>
+      {option.label}
+    </React.Fragment>
+  );
+}
+
 export default function SelectCustomOption() {
   return (
     <Select
@@ -20,27 +41,19 @@ export default function SelectCustomOption() {
         '--ListItemDecorator-size': '44px',
         minWidth: 240,
       }}
+      renderValue={renderValue}
     >
-      <Option value="1">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/1.jpg" />
-        </ListItemDecorator>
-        Eric
-      </Option>
-      <ListDivider role="none" inset="startContent" />
-      <Option value="2">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/2.jpg" />
-        </ListItemDecorator>
-        Smith
-      </Option>
-      <ListDivider role="none" inset="startContent" />
-      <Option value="3">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/3.jpg" />
-        </ListItemDecorator>
-        Erika
-      </Option>
+      {options.map((option, index) => (
+        <React.Fragment key={option.value}>
+          {index !== 0 ? <ListDivider role="none" inset="startContent" /> : null}
+          <Option value={option.value} label={option.label}>
+            <ListItemDecorator>
+              <Avatar size="sm" src={option.src} />
+            </ListItemDecorator>
+            {option.label}
+          </Option>
+        </React.Fragment>
+      ))}
     </Select>
   );
 }
diff --git a/docs/data/joy/components/select/SelectCustomOption.tsx b/docs/data/joy/components/select/SelectCustomOption.tsx
index d76aa7a3e3b8b3..cfef40ce1bfd4f 100644
--- a/docs/data/joy/components/select/SelectCustomOption.tsx
+++ b/docs/data/joy/components/select/SelectCustomOption.tsx
@@ -2,9 +2,30 @@ import * as React from 'react';
 import Avatar from '@mui/joy/Avatar';
 import ListItemDecorator from '@mui/joy/ListItemDecorator';
 import ListDivider from '@mui/joy/ListDivider';
-import Select from '@mui/joy/Select';
+import Select, { SelectOption } from '@mui/joy/Select';
 import Option from '@mui/joy/Option';
 
+const options = [
+  { value: '1', label: 'Eric', src: '/static/images/avatar/1.jpg' },
+  { value: '2', label: 'Smith', src: '/static/images/avatar/2.jpg' },
+  { value: '3', label: 'Erika', src: '/static/images/avatar/3.jpg' },
+];
+
+function renderValue(option: SelectOption<string> | null) {
+  if (!option) {
+    return null;
+  }
+
+  return (
+    <React.Fragment>
+      <ListItemDecorator>
+        <Avatar size="sm" src={options.find((o) => o.value === option.value)?.src} />
+      </ListItemDecorator>
+      {option.label}
+    </React.Fragment>
+  );
+}
+
 export default function SelectCustomOption() {
   return (
     <Select
@@ -20,27 +41,19 @@ export default function SelectCustomOption() {
         '--ListItemDecorator-size': '44px',
         minWidth: 240,
       }}
+      renderValue={renderValue}
     >
-      <Option value="1">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/1.jpg" />
-        </ListItemDecorator>
-        Eric
-      </Option>
-      <ListDivider role="none" inset="startContent" />
-      <Option value="2">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/2.jpg" />
-        </ListItemDecorator>
-        Smith
-      </Option>
-      <ListDivider role="none" inset="startContent" />
-      <Option value="3">
-        <ListItemDecorator>
-          <Avatar size="sm" src="/static/images/avatar/3.jpg" />
-        </ListItemDecorator>
-        Erika
-      </Option>
+      {options.map((option, index) => (
+        <React.Fragment key={option.value}>
+          {index !== 0 ? <ListDivider role="none" inset="startContent" /> : null}
+          <Option value={option.value} label={option.label}>
+            <ListItemDecorator>
+              <Avatar size="sm" src={option.src} />
+            </ListItemDecorator>
+            {option.label}
+          </Option>
+        </React.Fragment>
+      ))}
     </Select>
   );
 }

From 54b7875b1b5c444fc7e79a6dd434d0ce9d94d1bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 12:35:51 +0200
Subject: [PATCH 23/49] Update the description of the tabs API

---
 docs/translations/api-docs-joy/tabs/tabs.json               | 2 +-
 docs/translations/api-docs/tabs-unstyled/tabs-unstyled.json | 2 +-
 packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx         | 2 +-
 packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts    | 2 +-
 packages/mui-joy/src/Tabs/Tabs.tsx                          | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/translations/api-docs-joy/tabs/tabs.json b/docs/translations/api-docs-joy/tabs/tabs.json
index 9144d01ebb8a96..b0c46d7812c17f 100644
--- a/docs/translations/api-docs-joy/tabs/tabs.json
+++ b/docs/translations/api-docs-joy/tabs/tabs.json
@@ -11,7 +11,7 @@
     "selectionFollowsFocus": "If <code>true</code> the selected tab changes on focus. Otherwise it only changes on activation.",
     "size": "The size of the component. To learn how to add custom sizes to the component, check out <a href=\"/joy-ui/customization/themed-components/#extend-sizes\">Themed components—Extend sizes</a>.",
     "sx": "The system prop that allows defining system overrides as well as additional CSS styles. See the <a href=\"/system/getting-started/the-sx-prop/\">`sx` page</a> for more details.",
-    "value": "The value of the currently selected <code>Tab</code>. If you don&#39;t want any selected <code>Tab</code>, you can set this prop to <code>false</code>.",
+    "value": "The value of the currently selected <code>Tab</code>. If you don&#39;t want any selected <code>Tab</code>, you can set this prop to <code>null</code>.",
     "variant": "The <a href=\"https://mui.com/joy-ui/main-features/global-variants/\">global variant</a> to use. To learn how to add your own variants, check out <a href=\"/joy-ui/customization/themed-components/#extend-variants\">Themed components—Extend variants</a>."
   },
   "classDescriptions": {}
diff --git a/docs/translations/api-docs/tabs-unstyled/tabs-unstyled.json b/docs/translations/api-docs/tabs-unstyled/tabs-unstyled.json
index 275aa43ca2c933..eba130ac624180 100644
--- a/docs/translations/api-docs/tabs-unstyled/tabs-unstyled.json
+++ b/docs/translations/api-docs/tabs-unstyled/tabs-unstyled.json
@@ -10,7 +10,7 @@
     "selectionFollowsFocus": "If <code>true</code> the selected tab changes on focus. Otherwise it only changes on activation.",
     "slotProps": "The props used for each slot inside the Tabs.",
     "slots": "The components used for each slot inside the Tabs. Either a string to use a HTML element or a component. See <a href=\"#slots\">Slots API</a> below for more details.",
-    "value": "The value of the currently selected <code>Tab</code>. If you don&#39;t want any selected <code>Tab</code>, you can set this prop to <code>false</code>."
+    "value": "The value of the currently selected <code>Tab</code>. If you don&#39;t want any selected <code>Tab</code>, you can set this prop to <code>null</code>."
   },
   "classDescriptions": {},
   "slotDescriptions": { "root": "The component that renders the root." }
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
index b8b5ec71e8c599..144dc41dda0b9d 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.tsx
@@ -134,7 +134,7 @@ TabsUnstyled.propTypes /* remove-proptypes */ = {
   }),
   /**
    * The value of the currently selected `Tab`.
-   * If you don't want any selected `Tab`, you can set this prop to `false`.
+   * If you don't want any selected `Tab`, you can set this prop to `null`.
    */
   value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
 } as any;
diff --git a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
index 140b5820cb6e39..f18333fd9e5d7b 100644
--- a/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
+++ b/packages/mui-base/src/TabsUnstyled/TabsUnstyled.types.ts
@@ -15,7 +15,7 @@ export interface TabsUnstyledOwnProps {
   children?: React.ReactNode;
   /**
    * The value of the currently selected `Tab`.
-   * If you don't want any selected `Tab`, you can set this prop to `false`.
+   * If you don't want any selected `Tab`, you can set this prop to `null`.
    */
   value?: string | number | null;
   /**
diff --git a/packages/mui-joy/src/Tabs/Tabs.tsx b/packages/mui-joy/src/Tabs/Tabs.tsx
index 5d39deba4cbaeb..73abc62f7bbb3f 100644
--- a/packages/mui-joy/src/Tabs/Tabs.tsx
+++ b/packages/mui-joy/src/Tabs/Tabs.tsx
@@ -180,7 +180,7 @@ Tabs.propTypes /* remove-proptypes */ = {
   ]),
   /**
    * The value of the currently selected `Tab`.
-   * If you don't want any selected `Tab`, you can set this prop to `false`.
+   * If you don't want any selected `Tab`, you can set this prop to `null`.
    */
   value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   /**

From 6bcb7259e1f847b2fcf1bec3a121ee72978c8818 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 13:05:44 +0200
Subject: [PATCH 24/49] Don't try to focus a closed menu's item

---
 packages/mui-base/src/useMenu/useMenu.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 36fc653805b942..c63bf32ff8948c 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -95,7 +95,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
       if (field === 'open') {
         onOpenChange?.(fieldValue as boolean);
 
-        if (state.highlightedValue !== null) {
+        if (fieldValue === true && state.highlightedValue !== null) {
           subitems.get(state.highlightedValue)?.ref.current?.focus();
         }
       }

From 7f5c9c5191bbd6c2a881981341fbd4913cdf91e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 13:30:13 +0200
Subject: [PATCH 25/49] Revert unrelated changes

---
 .../mui-base/src/useList/useListChangeNotifiers.ts   |  4 ++--
 packages/mui-base/src/utils/useMessageBus.test.ts    | 12 ++++++------
 packages/mui-base/src/utils/useMessageBus.ts         | 10 +++++-----
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/mui-base/src/useList/useListChangeNotifiers.ts b/packages/mui-base/src/useList/useListChangeNotifiers.ts
index a39b5e9bf8973b..a5529fdb1ebe40 100644
--- a/packages/mui-base/src/useList/useListChangeNotifiers.ts
+++ b/packages/mui-base/src/useList/useListChangeNotifiers.ts
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import useMessageBus from '../utils/useMessageBus';
 
-const SELECTION_CHANGE_TOPIC = Symbol('change-selection');
-const HIGHLIGHT_CHANGE_TOPIC = Symbol('change-highlight');
+const SELECTION_CHANGE_TOPIC = 'select:change-selection';
+const HIGHLIGHT_CHANGE_TOPIC = 'select:change-highlight';
 
 export interface ListChangeNotifiers<ItemValue> {
   /**
diff --git a/packages/mui-base/src/utils/useMessageBus.test.ts b/packages/mui-base/src/utils/useMessageBus.test.ts
index dbdbe977b3f525..f7c495bb0698d7 100644
--- a/packages/mui-base/src/utils/useMessageBus.test.ts
+++ b/packages/mui-base/src/utils/useMessageBus.test.ts
@@ -5,7 +5,7 @@ import { createMessageBus } from './useMessageBus';
 describe('messageBus', () => {
   it('should be able to subscribe to a message', () => {
     const { subscribe, publish } = createMessageBus();
-    const testSubject = Symbol('test');
+    const testSubject = 'test';
     const callback = spy();
     subscribe(testSubject, callback);
     publish(testSubject, 'foo');
@@ -14,7 +14,7 @@ describe('messageBus', () => {
 
   it('should be able to unsubscribe from a message', () => {
     const { subscribe, publish } = createMessageBus();
-    const testSubject = Symbol('test');
+    const testSubject = 'test';
     const callback = spy();
     const unsubscribe = subscribe(testSubject, callback);
     unsubscribe();
@@ -24,8 +24,8 @@ describe('messageBus', () => {
 
   it('should be able to publish multiple messages', () => {
     const { subscribe, publish } = createMessageBus();
-    const testSubject1 = Symbol('test1');
-    const testSubject2 = Symbol('test2');
+    const testSubject1 = 'test1';
+    const testSubject2 = 'test2';
     const callback = spy();
     subscribe(testSubject1, callback);
     subscribe(testSubject2, callback);
@@ -36,8 +36,8 @@ describe('messageBus', () => {
 
   it('should be able to publish multiple messages with different arguments', () => {
     const { subscribe, publish } = createMessageBus();
-    const testSubject1 = Symbol('test1');
-    const testSubject2 = Symbol('test2');
+    const testSubject1 = 'test1';
+    const testSubject2 = 'test2';
     const callback = spy();
     subscribe(testSubject1, callback);
     subscribe(testSubject2, callback);
diff --git a/packages/mui-base/src/utils/useMessageBus.ts b/packages/mui-base/src/utils/useMessageBus.ts
index 79354a49ceb70e..ef2d8d9f898c4b 100644
--- a/packages/mui-base/src/utils/useMessageBus.ts
+++ b/packages/mui-base/src/utils/useMessageBus.ts
@@ -1,14 +1,14 @@
 import * as React from 'react';
 
 export interface MessageBus {
-  subscribe(topic: symbol, callback: Function): () => void;
-  publish(topic: symbol, ...args: unknown[]): void;
+  subscribe(topic: string, callback: Function): () => void;
+  publish(topic: string, ...args: unknown[]): void;
 }
 
 export function createMessageBus(): MessageBus {
-  const listeners = new Map<symbol, Set<Function>>();
+  const listeners = new Map<string, Set<Function>>();
 
-  function subscribe(topic: symbol, callback: Function) {
+  function subscribe(topic: string, callback: Function) {
     let topicListeners = listeners.get(topic);
     if (!topicListeners) {
       topicListeners = new Set([callback]);
@@ -25,7 +25,7 @@ export function createMessageBus(): MessageBus {
     };
   }
 
-  function publish(topic: symbol, ...args: unknown[]) {
+  function publish(topic: string, ...args: unknown[]) {
     const topicListeners = listeners.get(topic);
     if (topicListeners) {
       topicListeners.forEach((callback) => callback(...args));

From ff4bf702ae108703a522318e3773abddcf519bdb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 4 Apr 2023 20:23:46 +0200
Subject: [PATCH 26/49] Remove old code and update demos

---
 docs/data/base/components/menu/MenuSimple.js  | 42 +++++-----
 docs/data/base/components/menu/MenuSimple.tsx | 43 +++++-----
 .../menu/UnstyledMenuIntroduction.js          | 55 ++++++++-----
 .../menu/UnstyledMenuIntroduction.tsx         | 56 ++++++++-----
 docs/data/base/components/menu/UseMenu.js     | 80 +++++++++++-------
 docs/data/base/components/menu/UseMenu.tsx    | 82 +++++++++++--------
 .../base/components/menu/WrappedMenuItems.js  | 42 +++++-----
 .../base/components/menu/WrappedMenuItems.tsx | 43 +++++-----
 .../templates/email/components/Menu.tsx       | 36 +++++---
 .../templates/files/components/Menu.tsx       | 36 +++++---
 .../templates/team/components/Menu.tsx        | 36 +++++---
 docs/pages/base/api/menu-unstyled.json        |  1 -
 docs/pages/base/api/use-menu.json             | 15 ++--
 docs/pages/joy-ui/api/menu-list.json          |  2 +-
 .../api-docs/menu-unstyled/menu-unstyled.json |  1 -
 .../api-docs/use-menu/use-menu.json           |  3 +-
 .../src/MenuUnstyled/MenuUnstyled.tsx         | 26 ++----
 .../src/MenuUnstyled/MenuUnstyled.types.ts    | 15 +---
 .../mui-base/src/useList/listActions.types.ts |  1 +
 .../mui-base/src/useList/listReducer.test.ts  | 35 ++++----
 packages/mui-base/src/useList/listReducer.ts  |  7 +-
 packages/mui-base/src/useList/useList.ts      |  1 +
 packages/mui-base/src/useList/useListItem.ts  |  4 +-
 .../mui-base/src/useList/useListItem.types.ts |  9 +-
 packages/mui-base/src/useMenu/useMenu.ts      | 10 +--
 .../mui-base/src/useMenu/useMenu.types.ts     | 15 ++--
 packages/mui-joy/src/Menu/Menu.tsx            |  7 +-
 packages/mui-joy/src/MenuList/MenuList.tsx    | 10 +--
 28 files changed, 398 insertions(+), 315 deletions(-)

diff --git a/docs/data/base/components/menu/MenuSimple.js b/docs/data/base/components/menu/MenuSimple.js
index c371bcc9349d52..12a46816737323 100644
--- a/docs/data/base/components/menu/MenuSimple.js
+++ b/docs/data/base/components/menu/MenuSimple.js
@@ -5,14 +5,19 @@ import MenuItemUnstyled, {
 } from '@mui/base/MenuItemUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 export default function UnstyledMenuSimple() {
-  const [anchorEl, setAnchorEl] = React.useState(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef(null);
+  const [buttonElement, setButtonElement] = React.useState(null);
+
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef(null);
   const preventReopen = React.useRef(false);
 
+  const updateAnchor = React.useCallback((node) => {
+    setButtonElement(node);
+  }, []);
+
   const handleButtonClick = (event) => {
     if (preventReopen.current) {
       event.preventDefault();
@@ -20,11 +25,7 @@ export default function UnstyledMenuSimple() {
       return;
     }
 
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
-    }
+    setOpen((open) => !open);
   };
 
   const handleButtonMouseDown = () => {
@@ -38,22 +39,23 @@ export default function UnstyledMenuSimple() {
   const handleButtonKeyDown = (event) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current.focus();
-  };
-
   const createHandleMenuClick = (menuItem) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
 
@@ -64,7 +66,7 @@ export default function UnstyledMenuSimple() {
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'simple-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -76,11 +78,9 @@ export default function UnstyledMenuSimple() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/base/components/menu/MenuSimple.tsx b/docs/data/base/components/menu/MenuSimple.tsx
index fc27eb7c719038..dacfe9d167edab 100644
--- a/docs/data/base/components/menu/MenuSimple.tsx
+++ b/docs/data/base/components/menu/MenuSimple.tsx
@@ -5,14 +5,20 @@ import MenuItemUnstyled, {
 } from '@mui/base/MenuItemUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 export default function UnstyledMenuSimple() {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef<HTMLButtonElement>(null);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
   const preventReopen = React.useRef(false);
 
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
+
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     if (preventReopen.current) {
       event.preventDefault();
@@ -20,11 +26,7 @@ export default function UnstyledMenuSimple() {
       return;
     }
 
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
-    }
+    setOpen((open) => !open);
   };
 
   const handleButtonMouseDown = () => {
@@ -38,22 +40,23 @@ export default function UnstyledMenuSimple() {
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current!.focus();
-  };
-
   const createHandleMenuClick = (menuItem: string) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
 
@@ -64,7 +67,7 @@ export default function UnstyledMenuSimple() {
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'simple-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -76,11 +79,9 @@ export default function UnstyledMenuSimple() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/base/components/menu/UnstyledMenuIntroduction.js b/docs/data/base/components/menu/UnstyledMenuIntroduction.js
index 390c6a74a5856e..16c791f7fe572b 100644
--- a/docs/data/base/components/menu/UnstyledMenuIntroduction.js
+++ b/docs/data/base/components/menu/UnstyledMenuIntroduction.js
@@ -5,50 +5,67 @@ import MenuItemUnstyled, {
 } from '@mui/base/MenuItemUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 export default function UnstyledMenuIntroduction() {
-  const [anchorEl, setAnchorEl] = React.useState(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef(null);
+  const [buttonElement, setButtonElement] = React.useState(null);
+
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef(null);
+  const preventReopen = React.useRef(false);
+
+  const updateAnchor = React.useCallback((node) => {
+    setButtonElement(node);
+  }, []);
 
   const handleButtonClick = (event) => {
+    if (preventReopen.current) {
+      event.preventDefault();
+      preventReopen.current = false;
+      return;
+    }
+
+    setOpen((open) => !open);
+  };
+
+  const handleButtonMouseDown = () => {
     if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
+      // Prevents the menu from reopening right after closing
+      // when clicking the button.
+      preventReopen.current = true;
     }
   };
 
   const handleButtonKeyDown = (event) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current.focus();
-  };
-
   const createHandleMenuClick = (menuItem) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
-
   return (
     <div>
       <TriggerButton
         type="button"
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
-        ref={buttonRef}
+        onMouseDown={handleButtonMouseDown}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'simple-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -59,11 +76,9 @@ export default function UnstyledMenuIntroduction() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx b/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
index b00d854c514622..0304bbc43969f5 100644
--- a/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
+++ b/docs/data/base/components/menu/UnstyledMenuIntroduction.tsx
@@ -5,50 +5,68 @@ import MenuItemUnstyled, {
 } from '@mui/base/MenuItemUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 export default function UnstyledMenuIntroduction() {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef<HTMLButtonElement>(null);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
+  const preventReopen = React.useRef(false);
+
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
 
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (preventReopen.current) {
+      event.preventDefault();
+      preventReopen.current = false;
+      return;
+    }
+
+    setOpen((open) => !open);
+  };
+
+  const handleButtonMouseDown = () => {
     if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
+      // Prevents the menu from reopening right after closing
+      // when clicking the button.
+      preventReopen.current = true;
     }
   };
 
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current!.focus();
-  };
-
   const createHandleMenuClick = (menuItem: string) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
-
   return (
     <div>
       <TriggerButton
         type="button"
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
-        ref={buttonRef}
+        onMouseDown={handleButtonMouseDown}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'simple-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -59,11 +77,9 @@ export default function UnstyledMenuIntroduction() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/base/components/menu/UseMenu.js b/docs/data/base/components/menu/UseMenu.js
index dc1e408f4712f6..32263958a0195a 100644
--- a/docs/data/base/components/menu/UseMenu.js
+++ b/docs/data/base/components/menu/UseMenu.js
@@ -1,10 +1,10 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
+import clsx from 'clsx';
 import useMenu, { MenuProvider } from '@mui/base/useMenu';
 import useMenuItem from '@mui/base/useMenuItem';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { GlobalStyles } from '@mui/system';
-import clsx from 'clsx';
 
 const Menu = React.forwardRef(function Menu(props, ref) {
   const { children, onOpenChange, open, ...other } = props;
@@ -15,17 +15,9 @@ const Menu = React.forwardRef(function Menu(props, ref) {
     open,
   });
 
-  const menuContextValue = React.useMemo(
-    () => ({
-      ...contextValue,
-      open: true,
-    }),
-    [contextValue],
-  );
-
   return (
     <ul className="menu-root" {...other} {...getListboxProps()}>
-      <MenuProvider value={menuContextValue}>{children}</MenuProvider>
+      <MenuProvider value={contextValue}>{children}</MenuProvider>
     </ul>
   );
 });
@@ -37,7 +29,7 @@ Menu.propTypes = {
 };
 
 const MenuItem = React.forwardRef(function MenuItem(props, ref) {
-  const { children, ...other } = props;
+  const { children, onClick, ...other } = props;
 
   const { getRootProps, disabled, focusVisible } = useMenuItem({ ref });
 
@@ -48,7 +40,11 @@ const MenuItem = React.forwardRef(function MenuItem(props, ref) {
   };
 
   return (
-    <li className={clsx(classes)} {...other} {...getRootProps()}>
+    <li
+      className={clsx(classes)}
+      {...other}
+      {...getRootProps({ onClick: onClick ?? (() => {}) })}
+    >
       {children}
     </li>
   );
@@ -56,12 +52,18 @@ const MenuItem = React.forwardRef(function MenuItem(props, ref) {
 
 MenuItem.propTypes = {
   children: PropTypes.node,
+  onClick: PropTypes.func,
 };
 
 export default function UseMenu() {
-  const [anchorEl, setAnchorEl] = React.useState(null);
+  const [buttonElement, setButtonElement] = React.useState(null);
+
+  const [isOpen, setOpen] = React.useState(false);
   const preventReopen = React.useRef(false);
-  const buttonRef = React.useRef(null);
+
+  const updateAnchor = React.useCallback((node) => {
+    setButtonElement(node);
+  }, []);
 
   const handleOnClick = (event) => {
     if (preventReopen.current) {
@@ -70,26 +72,32 @@ export default function UseMenu() {
       return;
     }
 
-    setAnchorEl(anchorEl ? null : event.currentTarget);
-  };
-
-  const handleOpenChange = (isOpen) => {
-    if (!isOpen) {
-      setAnchorEl(null);
-      buttonRef.current.focus();
-    }
+    setOpen((open) => !open);
   };
 
-  const open = Boolean(anchorEl);
-
   const handleButtonMouseDown = () => {
-    if (open) {
+    if (isOpen) {
       // Prevents the menu from reopening right after closing
       // when clicking the button.
       preventReopen.current = true;
     }
   };
 
+  const handleButtonKeyDown = (event) => {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      setOpen(true);
+    }
+  };
+
+  const createHandleMenuClick = (menuItem) => {
+    return () => {
+      console.log(`Clicked on ${menuItem}`);
+      setOpen(false);
+      buttonElement?.focus();
+    };
+  };
+
   return (
     <React.Fragment>
       <GlobalStyles styles={styles} />
@@ -98,15 +106,25 @@ export default function UseMenu() {
         className="button"
         onClick={handleOnClick}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        onKeyDown={handleButtonKeyDown}
+        ref={updateAnchor}
+        aria-controls="hooks-menu"
+        aria-expanded={isOpen || undefined}
+        aria-haspopup="menu"
       >
         Commands
       </button>
-      <PopperUnstyled open={open} anchorEl={anchorEl}>
-        <Menu onOpenChange={handleOpenChange} open={open}>
-          <MenuItem>Cut</MenuItem>
-          <MenuItem>Copy</MenuItem>
-          <MenuItem>Paste</MenuItem>
+      <PopperUnstyled open={isOpen} anchorEl={buttonElement}>
+        <Menu
+          onOpenChange={(open) => {
+            setOpen(open);
+          }}
+          open={isOpen}
+          id="hooks-menu"
+        >
+          <MenuItem onClick={createHandleMenuClick('Cut')}>Cut</MenuItem>
+          <MenuItem onClick={createHandleMenuClick('Copy')}>Copy</MenuItem>
+          <MenuItem onClick={createHandleMenuClick('Paste')}>Paste</MenuItem>
         </Menu>
       </PopperUnstyled>
     </React.Fragment>
diff --git a/docs/data/base/components/menu/UseMenu.tsx b/docs/data/base/components/menu/UseMenu.tsx
index 75f0e4dbe8bc83..cb72abf94df1ff 100644
--- a/docs/data/base/components/menu/UseMenu.tsx
+++ b/docs/data/base/components/menu/UseMenu.tsx
@@ -1,9 +1,9 @@
 import * as React from 'react';
-import useMenu, { MenuProvider, MenuProviderValue } from '@mui/base/useMenu';
+import clsx from 'clsx';
+import useMenu, { MenuProvider } from '@mui/base/useMenu';
 import useMenuItem from '@mui/base/useMenuItem';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { GlobalStyles } from '@mui/system';
-import clsx from 'clsx';
 
 const Menu = React.forwardRef(function Menu(
   props: React.ComponentPropsWithoutRef<'ul'> & {
@@ -20,17 +20,9 @@ const Menu = React.forwardRef(function Menu(
     open,
   });
 
-  const menuContextValue: MenuProviderValue = React.useMemo(
-    () => ({
-      ...contextValue,
-      open: true,
-    }),
-    [contextValue],
-  );
-
   return (
     <ul className="menu-root" {...other} {...getListboxProps()}>
-      <MenuProvider value={menuContextValue}>{children}</MenuProvider>
+      <MenuProvider value={contextValue}>{children}</MenuProvider>
     </ul>
   );
 });
@@ -39,7 +31,7 @@ const MenuItem = React.forwardRef(function MenuItem(
   props: React.ComponentPropsWithoutRef<'li'>,
   ref: React.Ref<any>,
 ) {
-  const { children, ...other } = props;
+  const { children, onClick, ...other } = props;
 
   const { getRootProps, disabled, focusVisible } = useMenuItem({ ref });
 
@@ -50,16 +42,26 @@ const MenuItem = React.forwardRef(function MenuItem(
   };
 
   return (
-    <li className={clsx(classes)} {...other} {...getRootProps()}>
+    <li
+      className={clsx(classes)}
+      {...other}
+      {...getRootProps({ onClick: onClick ?? (() => {}) })}
+    >
       {children}
     </li>
   );
 });
 
 export default function UseMenu() {
-  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const preventReopen = React.useRef(false);
-  const buttonRef = React.useRef<HTMLButtonElement>(null);
+
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
 
   const handleOnClick = (event: React.MouseEvent<HTMLElement>) => {
     if (preventReopen.current) {
@@ -68,26 +70,32 @@ export default function UseMenu() {
       return;
     }
 
-    setAnchorEl(anchorEl ? null : event.currentTarget);
-  };
-
-  const handleOpenChange = (isOpen: boolean) => {
-    if (!isOpen) {
-      setAnchorEl(null);
-      buttonRef.current!.focus();
-    }
+    setOpen((open) => !open);
   };
 
-  const open = Boolean(anchorEl);
-
   const handleButtonMouseDown = () => {
-    if (open) {
+    if (isOpen) {
       // Prevents the menu from reopening right after closing
       // when clicking the button.
       preventReopen.current = true;
     }
   };
 
+  const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      setOpen(true);
+    }
+  };
+
+  const createHandleMenuClick = (menuItem: string) => {
+    return () => {
+      console.log(`Clicked on ${menuItem}`);
+      setOpen(false);
+      buttonElement?.focus();
+    };
+  };
+
   return (
     <React.Fragment>
       <GlobalStyles styles={styles} />
@@ -96,15 +104,25 @@ export default function UseMenu() {
         className="button"
         onClick={handleOnClick}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        onKeyDown={handleButtonKeyDown}
+        ref={updateAnchor}
+        aria-controls="hooks-menu"
+        aria-expanded={isOpen || undefined}
+        aria-haspopup="menu"
       >
         Commands
       </button>
-      <PopperUnstyled open={open} anchorEl={anchorEl}>
-        <Menu onOpenChange={handleOpenChange} open={open}>
-          <MenuItem>Cut</MenuItem>
-          <MenuItem>Copy</MenuItem>
-          <MenuItem>Paste</MenuItem>
+      <PopperUnstyled open={isOpen} anchorEl={buttonElement}>
+        <Menu
+          onOpenChange={(open) => {
+            setOpen(open);
+          }}
+          open={isOpen}
+          id="hooks-menu"
+        >
+          <MenuItem onClick={createHandleMenuClick('Cut')}>Cut</MenuItem>
+          <MenuItem onClick={createHandleMenuClick('Copy')}>Copy</MenuItem>
+          <MenuItem onClick={createHandleMenuClick('Paste')}>Paste</MenuItem>
         </Menu>
       </PopperUnstyled>
     </React.Fragment>
diff --git a/docs/data/base/components/menu/WrappedMenuItems.js b/docs/data/base/components/menu/WrappedMenuItems.js
index 5df545f0af4b82..2f88d313f182a5 100644
--- a/docs/data/base/components/menu/WrappedMenuItems.js
+++ b/docs/data/base/components/menu/WrappedMenuItems.js
@@ -7,6 +7,7 @@ import MenuItemUnstyled, {
 import { buttonUnstyledClasses } from '@mui/base/ButtonUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 function MenuSection({ children, label }) {
   return (
@@ -23,12 +24,16 @@ MenuSection.propTypes = {
 };
 
 export default function WrappedMenuItems() {
-  const [anchorEl, setAnchorEl] = React.useState(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef(null);
+  const [buttonElement, setButtonElement] = React.useState(null);
+
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef(null);
   const preventReopen = React.useRef(false);
 
+  const updateAnchor = React.useCallback((node) => {
+    setButtonElement(node);
+  }, []);
+
   const handleButtonClick = (event) => {
     if (preventReopen.current) {
       event.preventDefault();
@@ -36,11 +41,7 @@ export default function WrappedMenuItems() {
       return;
     }
 
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
-    }
+    setOpen((open) => !open);
   };
 
   const handleButtonMouseDown = () => {
@@ -54,22 +55,23 @@ export default function WrappedMenuItems() {
   const handleButtonKeyDown = (event) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current.focus();
-  };
-
   const createHandleMenuClick = (menuItem) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
 
@@ -80,7 +82,7 @@ export default function WrappedMenuItems() {
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'wrapped-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -91,11 +93,9 @@ export default function WrappedMenuItems() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/base/components/menu/WrappedMenuItems.tsx b/docs/data/base/components/menu/WrappedMenuItems.tsx
index dd7d7362ac912f..ccaf4e1d6ed30a 100644
--- a/docs/data/base/components/menu/WrappedMenuItems.tsx
+++ b/docs/data/base/components/menu/WrappedMenuItems.tsx
@@ -6,6 +6,7 @@ import MenuItemUnstyled, {
 import { buttonUnstyledClasses } from '@mui/base/ButtonUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
+import { ListActionTypes } from '@mui/base/useList';
 
 function MenuSection({ children, label }: MenuSectionProps) {
   return (
@@ -17,12 +18,17 @@ function MenuSection({ children, label }: MenuSectionProps) {
 }
 
 export default function WrappedMenuItems() {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
-  const buttonRef = React.useRef<HTMLButtonElement>(null);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
   const preventReopen = React.useRef(false);
 
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
+
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     if (preventReopen.current) {
       event.preventDefault();
@@ -30,11 +36,7 @@ export default function WrappedMenuItems() {
       return;
     }
 
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
-    }
+    setOpen((open) => !open);
   };
 
   const handleButtonMouseDown = () => {
@@ -48,22 +50,23 @@ export default function WrappedMenuItems() {
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        // Focus the last item when pressing ArrowUp.
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
-  const close = () => {
-    setAnchorEl(null);
-    buttonRef.current!.focus();
-  };
-
   const createHandleMenuClick = (menuItem: string) => {
     return () => {
       console.log(`Clicked on ${menuItem}`);
-      close();
+      setOpen(false);
+      buttonElement?.focus();
     };
   };
 
@@ -74,7 +77,7 @@ export default function WrappedMenuItems() {
         onClick={handleButtonClick}
         onKeyDown={handleButtonKeyDown}
         onMouseDown={handleButtonMouseDown}
-        ref={buttonRef}
+        ref={updateAnchor}
         aria-controls={isOpen ? 'wrapped-menu' : undefined}
         aria-expanded={isOpen || undefined}
         aria-haspopup="menu"
@@ -85,11 +88,9 @@ export default function WrappedMenuItems() {
         actions={menuActions}
         open={isOpen}
         onOpenChange={(open) => {
-          if (!open) {
-            close();
-          }
+          setOpen(open);
         }}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         slots={{ root: Popper, listbox: StyledListbox }}
         slotProps={{ listbox: { id: 'simple-menu' } }}
       >
diff --git a/docs/data/joy/getting-started/templates/email/components/Menu.tsx b/docs/data/joy/getting-started/templates/email/components/Menu.tsx
index 8b0ada4a62577b..3dd506947a3997 100644
--- a/docs/data/joy/getting-started/templates/email/components/Menu.tsx
+++ b/docs/data/joy/getting-started/templates/email/components/Menu.tsx
@@ -1,6 +1,7 @@
 import * as React from 'react';
 import JoyMenu, { MenuUnstyledActions } from '@mui/joy/Menu';
 import MenuItem from '@mui/joy/MenuItem';
+import { ListActionTypes } from '@mui/base/useList';
 
 function Menu({
   control,
@@ -11,31 +12,44 @@ function Menu({
   id: string;
   menus: Array<{ label: string } & { [k: string]: any }>;
 }) {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const buttonRef = React.useRef<HTMLButtonElement>(null);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
+  const preventReopen = React.useRef(false);
+
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
 
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
+    if (preventReopen.current) {
+      event.preventDefault();
+      preventReopen.current = false;
+      return;
     }
+
+    setOpen((open) => !open);
   };
 
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
   const close = () => {
-    setAnchorEl(null);
+    setOpen(false);
     buttonRef.current!.focus();
   };
 
@@ -45,7 +59,7 @@ function Menu({
         type: 'button',
         onClick: handleButtonClick,
         onKeyDown: handleButtonKeyDown,
-        ref: buttonRef,
+        ref: updateAnchor,
         'aria-controls': isOpen ? id : undefined,
         'aria-expanded': isOpen || undefined,
         'aria-haspopup': 'menu',
@@ -56,7 +70,7 @@ function Menu({
         actions={menuActions}
         open={isOpen}
         onClose={close}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         sx={{ minWidth: 120 }}
       >
         {menus.map(({ label, active, ...item }) => {
diff --git a/docs/data/joy/getting-started/templates/files/components/Menu.tsx b/docs/data/joy/getting-started/templates/files/components/Menu.tsx
index 8b0ada4a62577b..3dd506947a3997 100644
--- a/docs/data/joy/getting-started/templates/files/components/Menu.tsx
+++ b/docs/data/joy/getting-started/templates/files/components/Menu.tsx
@@ -1,6 +1,7 @@
 import * as React from 'react';
 import JoyMenu, { MenuUnstyledActions } from '@mui/joy/Menu';
 import MenuItem from '@mui/joy/MenuItem';
+import { ListActionTypes } from '@mui/base/useList';
 
 function Menu({
   control,
@@ -11,31 +12,44 @@ function Menu({
   id: string;
   menus: Array<{ label: string } & { [k: string]: any }>;
 }) {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const buttonRef = React.useRef<HTMLButtonElement>(null);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
+  const preventReopen = React.useRef(false);
+
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
 
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
+    if (preventReopen.current) {
+      event.preventDefault();
+      preventReopen.current = false;
+      return;
     }
+
+    setOpen((open) => !open);
   };
 
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
   const close = () => {
-    setAnchorEl(null);
+    setOpen(false);
     buttonRef.current!.focus();
   };
 
@@ -45,7 +59,7 @@ function Menu({
         type: 'button',
         onClick: handleButtonClick,
         onKeyDown: handleButtonKeyDown,
-        ref: buttonRef,
+        ref: updateAnchor,
         'aria-controls': isOpen ? id : undefined,
         'aria-expanded': isOpen || undefined,
         'aria-haspopup': 'menu',
@@ -56,7 +70,7 @@ function Menu({
         actions={menuActions}
         open={isOpen}
         onClose={close}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         sx={{ minWidth: 120 }}
       >
         {menus.map(({ label, active, ...item }) => {
diff --git a/docs/data/joy/getting-started/templates/team/components/Menu.tsx b/docs/data/joy/getting-started/templates/team/components/Menu.tsx
index 8b0ada4a62577b..3dd506947a3997 100644
--- a/docs/data/joy/getting-started/templates/team/components/Menu.tsx
+++ b/docs/data/joy/getting-started/templates/team/components/Menu.tsx
@@ -1,6 +1,7 @@
 import * as React from 'react';
 import JoyMenu, { MenuUnstyledActions } from '@mui/joy/Menu';
 import MenuItem from '@mui/joy/MenuItem';
+import { ListActionTypes } from '@mui/base/useList';
 
 function Menu({
   control,
@@ -11,31 +12,44 @@ function Menu({
   id: string;
   menus: Array<{ label: string } & { [k: string]: any }>;
 }) {
-  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);
-  const isOpen = Boolean(anchorEl);
+  const [buttonElement, setButtonElement] = React.useState<HTMLButtonElement | null>(
+    null,
+  );
+  const [isOpen, setOpen] = React.useState(false);
   const buttonRef = React.useRef<HTMLButtonElement>(null);
   const menuActions = React.useRef<MenuUnstyledActions>(null);
+  const preventReopen = React.useRef(false);
+
+  const updateAnchor = React.useCallback((node: HTMLButtonElement | null) => {
+    setButtonElement(node);
+  }, []);
 
   const handleButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    if (isOpen) {
-      setAnchorEl(null);
-    } else {
-      setAnchorEl(event.currentTarget);
+    if (preventReopen.current) {
+      event.preventDefault();
+      preventReopen.current = false;
+      return;
     }
+
+    setOpen((open) => !open);
   };
 
   const handleButtonKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
       event.preventDefault();
-      setAnchorEl(event.currentTarget);
+      setOpen(true);
       if (event.key === 'ArrowUp') {
-        menuActions.current?.highlightLastItem();
+        menuActions.current?.dispatch({
+          type: ListActionTypes.keyDown,
+          key: event.key,
+          event,
+        });
       }
     }
   };
 
   const close = () => {
-    setAnchorEl(null);
+    setOpen(false);
     buttonRef.current!.focus();
   };
 
@@ -45,7 +59,7 @@ function Menu({
         type: 'button',
         onClick: handleButtonClick,
         onKeyDown: handleButtonKeyDown,
-        ref: buttonRef,
+        ref: updateAnchor,
         'aria-controls': isOpen ? id : undefined,
         'aria-expanded': isOpen || undefined,
         'aria-haspopup': 'menu',
@@ -56,7 +70,7 @@ function Menu({
         actions={menuActions}
         open={isOpen}
         onClose={close}
-        anchorEl={anchorEl}
+        anchorEl={buttonElement}
         sx={{ minWidth: 120 }}
       >
         {menus.map(({ label, active, ...item }) => {
diff --git a/docs/pages/base/api/menu-unstyled.json b/docs/pages/base/api/menu-unstyled.json
index 757a82d53fc888..083ffad46200e1 100644
--- a/docs/pages/base/api/menu-unstyled.json
+++ b/docs/pages/base/api/menu-unstyled.json
@@ -8,7 +8,6 @@
       }
     },
     "component": { "type": { "name": "elementType" } },
-    "keepMounted": { "type": { "name": "bool" }, "default": "false" },
     "onOpenChange": { "type": { "name": "func" } },
     "open": { "type": { "name": "bool" }, "default": "false" },
     "slotProps": {
diff --git a/docs/pages/base/api/use-menu.json b/docs/pages/base/api/use-menu.json
index 703a5b5479945b..dafd94da42449b 100644
--- a/docs/pages/base/api/use-menu.json
+++ b/docs/pages/base/api/use-menu.json
@@ -15,6 +15,13 @@
       "type": { "name": "MenuProviderValue", "description": "MenuProviderValue" },
       "required": true
     },
+    "dispatch": {
+      "type": {
+        "name": "(action: ListAction&lt;string, MenuInternalState&gt;) =&gt; void",
+        "description": "(action: ListAction&lt;string, MenuInternalState&gt;) =&gt; void"
+      },
+      "required": true
+    },
     "getListboxProps": {
       "type": {
         "name": "&lt;TOther extends EventHandlers&gt;(otherHandlers?: TOther) =&gt; UseMenuListboxSlotProps",
@@ -26,14 +33,6 @@
       "type": { "name": "string | null", "description": "string | null" },
       "required": true
     },
-    "highlightFirstItem": {
-      "type": { "name": "() =&gt; void", "description": "() =&gt; void" },
-      "required": true
-    },
-    "highlightLastItem": {
-      "type": { "name": "() =&gt; void", "description": "() =&gt; void" },
-      "required": true
-    },
     "menuItems": {
       "type": {
         "name": "Map&lt;string, MenuItemMetadata&gt;",
diff --git a/docs/pages/joy-ui/api/menu-list.json b/docs/pages/joy-ui/api/menu-list.json
index 5bb9eeb9244afd..d6aaeb89f3e39f 100644
--- a/docs/pages/joy-ui/api/menu-list.json
+++ b/docs/pages/joy-ui/api/menu-list.json
@@ -3,7 +3,7 @@
     "actions": {
       "type": {
         "name": "union",
-        "description": "func<br>&#124;&nbsp;{ current?: { highlightFirstItem: func, highlightLastItem: func } }"
+        "description": "func<br>&#124;&nbsp;{ current?: { dispatch: func } }"
       }
     },
     "color": {
diff --git a/docs/translations/api-docs/menu-unstyled/menu-unstyled.json b/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
index 2ca38098db4181..f8b722f8758117 100644
--- a/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
+++ b/docs/translations/api-docs/menu-unstyled/menu-unstyled.json
@@ -4,7 +4,6 @@
     "actions": "A ref with imperative actions. It allows to select the first or last menu item.",
     "anchorEl": "An HTML element, <a href=\"https://popper.js.org/docs/v2/virtual-elements/\">virtualElement</a>, or a function that returns either. It&#39;s used to set the position of the popper.",
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
-    "keepMounted": "Always keep the menu in the DOM. This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.",
     "onOpenChange": "Triggered when focus leaves the menu and the menu should close.",
     "open": "Controls whether the menu is displayed.",
     "slotProps": "The props used for each slot inside the Menu.",
diff --git a/docs/translations/api-docs/use-menu/use-menu.json b/docs/translations/api-docs/use-menu/use-menu.json
index fb50e975089198..5dfdec77f9b666 100644
--- a/docs/translations/api-docs/use-menu/use-menu.json
+++ b/docs/translations/api-docs/use-menu/use-menu.json
@@ -3,10 +3,9 @@
   "parametersDescriptions": {},
   "returnValueDescriptions": {
     "contextValue": "The value to be passed into the MenuProvider.",
+    "dispatch": "Action dispatcher for the menu component.\nAllows to programmatically control the menu.",
     "getListboxProps": "Resolver for the listbox component's props.",
     "highlightedOption": "The highlighted option in the menu listbox.",
-    "highlightFirstItem": "Callback for highlighting the first item in the menu listbox.",
-    "highlightLastItem": "Callback for highlighting the last item in the menu listbox.",
     "menuItems": "Items in the menu listbox.",
     "open": "If <code>true</code>, the menu is open."
   }
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
index 946eeb77dbdd2e..245ca1fccaaa9c 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.tsx
@@ -44,18 +44,17 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
     children,
     component,
     defaultOpen,
-    keepMounted = false,
     listboxId,
     onOpenChange,
-    open,
+    open: openProp,
     slotProps = {},
     slots = {},
     ...other
   } = props;
 
-  const { contextValue, getListboxProps, highlightFirstItem, highlightLastItem } = useMenu({
+  const { contextValue, getListboxProps, dispatch, open } = useMenu({
     defaultOpen,
-    open,
+    open: openProp,
     onOpenChange,
     listboxId,
   });
@@ -63,16 +62,12 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
   React.useImperativeHandle(
     actions,
     () => ({
-      highlightFirstItem,
-      highlightLastItem,
+      dispatch,
     }),
-    [highlightFirstItem, highlightLastItem],
+    [dispatch],
   );
 
-  const ownerState: MenuUnstyledOwnerState = {
-    ...props,
-    keepMounted,
-  };
+  const ownerState: MenuUnstyledOwnerState = { ...props, open };
 
   const classes = useUtilityClasses(ownerState);
 
@@ -84,7 +79,7 @@ const MenuUnstyled = React.forwardRef(function MenuUnstyled<
     additionalProps: {
       anchorEl,
       open,
-      keepMounted,
+      keepMounted: true,
       role: undefined,
       ref: forwardedRef,
     },
@@ -143,13 +138,6 @@ MenuUnstyled.propTypes /* remove-proptypes */ = {
    * @ignore
    */
   defaultOpen: PropTypes.bool,
-  /**
-   * Always keep the menu in the DOM.
-   * This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.
-   *
-   * @default false
-   */
-  keepMounted: PropTypes.bool,
   /**
    * @ignore
    */
diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
index f5ec8b9feb0607..93dbfff3985f26 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
@@ -2,14 +2,14 @@ import { OverrideProps } from '@mui/types';
 import * as React from 'react';
 import PopperUnstyled, { PopperUnstyledProps } from '../PopperUnstyled';
 import { SlotComponentProps } from '../utils';
-import { UseMenuListboxSlotProps } from '../useMenu';
+import { MenuInternalState, UseMenuListboxSlotProps } from '../useMenu';
+import { ListAction } from '../useList';
 
 export interface MenuUnstyledRootSlotPropsOverrides {}
 export interface MenuUnstyledListboxSlotPropsOverrides {}
 
 export interface MenuUnstyledActions {
-  highlightFirstItem: () => void;
-  highlightLastItem: () => void;
+  dispatch: (action: ListAction<string, MenuInternalState>) => void;
 }
 
 export interface MenuUnstyledOwnProps {
@@ -27,13 +27,6 @@ export interface MenuUnstyledOwnProps {
   children?: React.ReactNode;
   className?: string;
   defaultOpen?: boolean;
-  /**
-   * Always keep the menu in the DOM.
-   * This prop can be useful in SEO situation or when you want to maximize the responsiveness of the Menu.
-   *
-   * @default false
-   */
-  keepMounted?: boolean;
   listboxId?: string;
   /**
    * Triggered when focus leaves the menu and the menu should close.
@@ -93,7 +86,7 @@ export type MenuUnstyledProps<
 };
 
 export interface MenuUnstyledOwnerState extends MenuUnstyledOwnProps {
-  keepMounted: boolean;
+  open: boolean;
 }
 
 export type MenuUnstyledRootSlotProps = {
diff --git a/packages/mui-base/src/useList/listActions.types.ts b/packages/mui-base/src/useList/listActions.types.ts
index 89c98d38154ec8..f15e8e6e77b0c7 100644
--- a/packages/mui-base/src/useList/listActions.types.ts
+++ b/packages/mui-base/src/useList/listActions.types.ts
@@ -36,6 +36,7 @@ interface BlurAction {
 
 interface KeyDownAction {
   type: typeof ListActionTypes.keyDown;
+  key: string;
   event: React.KeyboardEvent;
 }
 
diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index e9835ba7a6e7be..c1de2d029400ee 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -193,9 +193,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'Home',
-          } as any,
+          key: 'Home',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three', 'four', 'five'],
@@ -225,9 +224,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'End',
-          } as any,
+          key: 'End',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three', 'four', 'five'],
@@ -257,9 +255,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'ArrowUp',
-          } as any,
+          key: 'ArrowUp',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three', 'four', 'five'],
@@ -289,9 +286,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'ArrowDown',
-          } as any,
+          key: 'ArrowDown',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three', 'four', 'five'],
@@ -319,9 +315,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'ArrowDown',
-          } as any,
+          key: 'ArrowDown',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three', 'four', 'five'],
@@ -351,9 +346,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'Enter',
-          } as any,
+          key: 'Enter',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three'],
@@ -381,9 +375,8 @@ describe('listReducer', () => {
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          event: {
-            key: 'Enter',
-          } as any,
+          key: 'Enter',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three'],
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index 343f9d24144f1b..a96423cf072c9b 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -1,4 +1,3 @@
-import * as React from 'react';
 import { ListActionTypes } from './listActions.types';
 import {
   ListState,
@@ -224,14 +223,14 @@ function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
 }
 
 function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
-  event: React.KeyboardEvent,
+  key: string,
   state: State,
   parameters: ListActionAddOnValue<ItemValue>,
 ): State {
   const previouslySelectedValue = state.highlightedValue;
   const { orientation } = parameters;
 
-  switch (event.key) {
+  switch (key) {
     case 'Home':
       return {
         ...state,
@@ -423,7 +422,7 @@ export default function listReducer<ItemValue, State extends ListState<ItemValue
 
   switch (type) {
     case ListActionTypes.keyDown:
-      return handleKeyDown(action.event, state, parameters);
+      return handleKeyDown(action.key, state, parameters);
     case ListActionTypes.itemClick:
       return handleItemSelection(action.item, state, parameters);
     case ListActionTypes.blur:
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 334fd951fff32a..33c2e354238e29 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -291,6 +291,7 @@ function useList<
 
       dispatch({
         type: ListActionTypes.keyDown,
+        key: event.key,
         event,
       });
 
diff --git a/packages/mui-base/src/useList/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
index f55ed70b2e3f57..68c08de242e57a 100644
--- a/packages/mui-base/src/useList/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -20,7 +20,7 @@ import { ListContext } from './ListContext';
 export default function useListItem<ItemValue>(
   parameters: UseListItemParameters<ItemValue>,
 ): UseListItemReturnValue {
-  const { item, ref: externalRef } = parameters;
+  const { handlePointerOverEvents = false, item, ref: externalRef } = parameters;
 
   const itemRef = React.useRef<HTMLElement>(null);
   const handleRef = useForkRef(itemRef, externalRef);
@@ -107,7 +107,7 @@ export default function useListItem<ItemValue>(
   ) => ({
     ...otherHandlers,
     onClick: createHandleClick(otherHandlers),
-    onPointerOver: createHandlePointerOver(otherHandlers),
+    onPointerOver: handlePointerOverEvents ? createHandlePointerOver(otherHandlers) : undefined,
     ref: handleRef,
     tabIndex,
   });
diff --git a/packages/mui-base/src/useList/useListItem.types.ts b/packages/mui-base/src/useList/useListItem.types.ts
index 23ce56b6dc0aa3..ffd150333b4725 100644
--- a/packages/mui-base/src/useList/useListItem.types.ts
+++ b/packages/mui-base/src/useList/useListItem.types.ts
@@ -1,6 +1,13 @@
 import { EventHandlers } from '../utils';
 
 export interface UseListItemParameters<ItemValue> {
+  /**
+   * If `true`, the list item will dispatch the `itemHover` action on pointer over.
+   * Since the use cases for it are rare, it's disabled by default.
+   *
+   * @default false
+   */
+  handlePointerOverEvents?: boolean;
   /**
    * The list item.
    */
@@ -14,7 +21,7 @@ export interface UseListItemParameters<ItemValue> {
 interface UseListItemRootSlotOwnProps {
   id?: string;
   onClick: React.MouseEventHandler;
-  onPointerOver: React.PointerEventHandler;
+  onPointerOver: React.PointerEventHandler | undefined;
   tabIndex?: number;
 }
 
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index c63bf32ff8948c..a9e342324dcbe3 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -46,7 +46,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     [subitems],
   );
 
-  const stateReducer = React.useCallback(
+  const menuReducer = React.useCallback(
     (
       state: MenuInternalState,
       action: ListAction<string, MenuInternalState> & ListActionAddOn<string>,
@@ -79,6 +79,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
           return {
             ...newState,
             open: false,
+            highlightedValue: action.props.current!.items[0],
           };
         }
       }
@@ -104,6 +105,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
   );
 
   const {
+    dispatch,
     getRootProps,
     highlightedOption,
     contextValue: listContextValue,
@@ -125,7 +127,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     listRef: handleRef,
     onStateChange: stateChangeHandler,
     selectionLimit: 0,
-    stateReducer,
+    stateReducer: menuReducer,
   });
 
   React.useEffect(() => {
@@ -159,11 +161,9 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
       ...compoundComponentContextValue,
       ...listContextValue,
     },
+    dispatch,
     getListboxProps,
     highlightedOption,
-    // TODO: remove
-    highlightFirstItem: () => {},
-    highlightLastItem: () => {},
     menuItems: subitems,
     open,
   };
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 4b753153e1ee13..3f17c46ae9d9d7 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { ListState, UseListRootSlotProps } from '../useList';
+import { ListAction, ListState, UseListRootSlotProps } from '../useList';
 import { MenuItemMetadata } from '../useMenuItem';
 import { EventHandlers } from '../utils/types';
 import { MenuProviderValue } from './MenuProvider';
@@ -17,6 +17,11 @@ export interface UseMenuReturnValue {
    * The value to be passed into the MenuProvider.
    */
   contextValue: MenuProviderValue;
+  /**
+   * Action dispatcher for the menu component.
+   * Allows to programmatically control the menu.
+   */
+  dispatch: (action: ListAction<string, MenuInternalState>) => void;
   /**
    * Resolver for the listbox component's props.
    * @param otherHandlers event handlers for the listbox component
@@ -29,14 +34,6 @@ export interface UseMenuReturnValue {
    * The highlighted option in the menu listbox.
    */
   highlightedOption: string | null;
-  /**
-   * Callback for highlighting the first item in the menu listbox.
-   */
-  highlightFirstItem: () => void;
-  /**
-   * Callback for highlighting the last item in the menu listbox.
-   */
-  highlightLastItem: () => void;
   /**
    * Items in the menu listbox.
    */
diff --git a/packages/mui-joy/src/Menu/Menu.tsx b/packages/mui-joy/src/Menu/Menu.tsx
index 5e38a71de3d32a..ba0714934ca616 100644
--- a/packages/mui-joy/src/Menu/Menu.tsx
+++ b/packages/mui-joy/src/Menu/Menu.tsx
@@ -98,7 +98,7 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
     [onClose],
   );
 
-  const { contextValue, getListboxProps, highlightFirstItem, highlightLastItem } = useMenu({
+  const { contextValue, getListboxProps, dispatch } = useMenu({
     open,
     onOpenChange: handleOpenChange,
     listboxId: id,
@@ -107,10 +107,9 @@ const Menu = React.forwardRef(function Menu(inProps, ref) {
   React.useImperativeHandle(
     actions,
     () => ({
-      highlightFirstItem,
-      highlightLastItem,
+      dispatch,
     }),
-    [highlightFirstItem, highlightLastItem],
+    [dispatch],
   );
 
   const ownerState = {
diff --git a/packages/mui-joy/src/MenuList/MenuList.tsx b/packages/mui-joy/src/MenuList/MenuList.tsx
index edb175ad181fb8..24ad9bf5dc4c52 100644
--- a/packages/mui-joy/src/MenuList/MenuList.tsx
+++ b/packages/mui-joy/src/MenuList/MenuList.tsx
@@ -77,7 +77,7 @@ const MenuList = React.forwardRef(function MenuList(inProps, ref) {
   const { getColor } = useColorInversion(variant);
   const color = getColor(inProps.color, colorProp);
 
-  const { contextValue, getListboxProps, highlightFirstItem, highlightLastItem } = useMenu({
+  const { contextValue, getListboxProps, dispatch } = useMenu({
     listboxRef: ref,
     listboxId: idProp,
   });
@@ -85,10 +85,9 @@ const MenuList = React.forwardRef(function MenuList(inProps, ref) {
   React.useImperativeHandle(
     actions,
     () => ({
-      highlightFirstItem,
-      highlightLastItem,
+      dispatch,
     }),
-    [highlightFirstItem, highlightLastItem],
+    [dispatch],
   );
 
   const ownerState = {
@@ -148,8 +147,7 @@ MenuList.propTypes /* remove-proptypes */ = {
     PropTypes.func,
     PropTypes.shape({
       current: PropTypes.shape({
-        highlightFirstItem: PropTypes.func.isRequired,
-        highlightLastItem: PropTypes.func.isRequired,
+        dispatch: PropTypes.func.isRequired,
       }),
     }),
   ]),

From b97ed12e12cc0afb2214b7d6a676be174f6ef682 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 5 Apr 2023 00:40:24 +0200
Subject: [PATCH 27/49] Restart CI


From e9a6afe7bda3c230f2e0ed43d14596d9a60dad87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 5 Apr 2023 10:57:29 +0200
Subject: [PATCH 28/49] Docs + small changes

---
 .../select/UnstyledSelectCustomRenderValue.js |   2 +-
 .../UnstyledSelectCustomRenderValue.tsx       |   2 +-
 docs/data/base/components/select/UseSelect.js |   4 +-
 .../data/base/components/select/UseSelect.tsx |   4 +-
 docs/pages/base/api/use-menu.json             |   2 +-
 docs/pages/base/api/use-select.json           |  50 +++++++-
 docs/pages/base/api/use-tabs-list.json        |  24 ----
 .../select-unstyled/select-unstyled.json      |   4 +-
 .../tab-panel-unstyled.json                   |   2 +-
 .../api-docs/use-menu/use-menu.json           |   8 +-
 .../api-docs/use-select/use-select.json       |  18 ++-
 .../api-docs/use-tab-panel/use-tab-panel.json |   1 +
 .../api-docs/use-tab/use-tab.json             |   2 +
 .../api-docs/use-tabs-list/use-tabs-list.json |   6 +-
 .../src/OptionUnstyled/OptionUnstyled.tsx     |   2 +
 .../src/SelectUnstyled/SelectUnstyled.tsx     |   2 +-
 .../SelectUnstyled/SelectUnstyled.types.ts    |   2 +-
 .../src/TabPanelUnstyled/TabPanelUnstyled.tsx |   2 +
 .../TabPanelUnstyled.types.ts                 |   2 +
 .../mui-base/src/useList/useList.types.ts     |  13 +-
 .../mui-base/src/useMenu/useMenu.types.ts     |  20 +++
 packages/mui-base/src/useSelect/useSelect.ts  |   4 +-
 .../mui-base/src/useSelect/useSelect.types.ts | 118 ++++++++++++++++--
 packages/mui-base/src/useTab/useTab.types.ts  |   6 +
 .../src/useTabPanel/useTabPanel.types.ts      |   3 +
 .../mui-base/src/useTabsList/useTabsList.ts   |   8 +-
 .../src/useTabsList/useTabsList.types.ts      |  22 +---
 .../mui-base/src/utils/useCompoundItem.ts     |   8 ++
 28 files changed, 256 insertions(+), 85 deletions(-)

diff --git a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
index 5678659442536f..81ec6bd3813ece 100644
--- a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
+++ b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.js
@@ -1,8 +1,8 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import SelectUnstyled, { selectUnstyledClasses } from '@mui/base/SelectUnstyled';
-import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
 
+import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
 
diff --git a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
index de63a1223f98dc..744690ccab9cdd 100644
--- a/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
+++ b/docs/data/base/components/select/UnstyledSelectCustomRenderValue.tsx
@@ -3,8 +3,8 @@ import SelectUnstyled, {
   SelectUnstyledProps,
   selectUnstyledClasses,
 } from '@mui/base/SelectUnstyled';
-import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
 import { SelectOption } from '@mui/base/useOption';
+import OptionUnstyled, { optionUnstyledClasses } from '@mui/base/OptionUnstyled';
 import PopperUnstyled from '@mui/base/PopperUnstyled';
 import { styled } from '@mui/system';
 
diff --git a/docs/data/base/components/select/UseSelect.js b/docs/data/base/components/select/UseSelect.js
index 22ecdf2d1f02a1..06dee98243853f 100644
--- a/docs/data/base/components/select/UseSelect.js
+++ b/docs/data/base/components/select/UseSelect.js
@@ -1,10 +1,10 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { styled } from '@mui/system';
-import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 import clsx from 'clsx';
 import useSelect, { SelectProvider } from '@mui/base/useSelect';
 import useOption from '@mui/base/useOption';
+import { styled } from '@mui/system';
+import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 
 const blue = {
   100: '#DAECFF',
diff --git a/docs/data/base/components/select/UseSelect.tsx b/docs/data/base/components/select/UseSelect.tsx
index 78b115c97e309d..d63b5ab70d13ee 100644
--- a/docs/data/base/components/select/UseSelect.tsx
+++ b/docs/data/base/components/select/UseSelect.tsx
@@ -1,12 +1,12 @@
 import * as React from 'react';
-import { styled } from '@mui/system';
-import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 import clsx from 'clsx';
 import useSelect, {
   SelectOptionDefinition,
   SelectProvider,
 } from '@mui/base/useSelect';
 import useOption from '@mui/base/useOption';
+import { styled } from '@mui/system';
+import UnfoldMoreRoundedIcon from '@mui/icons-material/UnfoldMoreRounded';
 
 const blue = {
   100: '#DAECFF',
diff --git a/docs/pages/base/api/use-menu.json b/docs/pages/base/api/use-menu.json
index dafd94da42449b..59c8e6213c3a0b 100644
--- a/docs/pages/base/api/use-menu.json
+++ b/docs/pages/base/api/use-menu.json
@@ -1,6 +1,6 @@
 {
   "parameters": {
-    "defaultOpen": { "type": { "name": "boolean", "description": "boolean" } },
+    "defaultOpen": { "type": { "name": "boolean", "description": "boolean" }, "default": "false" },
     "listboxId": { "type": { "name": "string", "description": "string" } },
     "listboxRef": {
       "type": { "name": "React.Ref&lt;any&gt;", "description": "React.Ref&lt;any&gt;" }
diff --git a/docs/pages/base/api/use-select.json b/docs/pages/base/api/use-select.json
index 767592822eb19c..1a42b2162b207b 100644
--- a/docs/pages/base/api/use-select.json
+++ b/docs/pages/base/api/use-select.json
@@ -1,6 +1,54 @@
 {
   "parameters": {},
-  "returnValue": {},
+  "returnValue": {
+    "buttonActive": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "buttonFocusVisible": {
+      "type": { "name": "boolean", "description": "boolean" },
+      "required": true
+    },
+    "contextValue": {
+      "type": {
+        "name": "SelectProviderValue&lt;Value&gt;",
+        "description": "SelectProviderValue&lt;Value&gt;"
+      },
+      "required": true
+    },
+    "disabled": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "getButtonProps": {
+      "type": {
+        "name": "&lt;OtherHandlers extends EventHandlers = {}&gt;(otherHandlers?: OtherHandlers) =&gt; UseSelectButtonSlotProps&lt;OtherHandlers&gt;",
+        "description": "&lt;OtherHandlers extends EventHandlers = {}&gt;(otherHandlers?: OtherHandlers) =&gt; UseSelectButtonSlotProps&lt;OtherHandlers&gt;"
+      },
+      "required": true
+    },
+    "getListboxProps": {
+      "type": {
+        "name": "&lt;OtherHandlers extends EventHandlers = {}&gt;(otherHandlers?: OtherHandlers) =&gt; UseSelectListboxSlotProps&lt;OtherHandlers&gt;",
+        "description": "&lt;OtherHandlers extends EventHandlers = {}&gt;(otherHandlers?: OtherHandlers) =&gt; UseSelectListboxSlotProps&lt;OtherHandlers&gt;"
+      },
+      "required": true
+    },
+    "getOptionMetadata": {
+      "type": {
+        "name": "(optionValue: Value) =&gt; SelectOption&lt;Value&gt; | undefined",
+        "description": "(optionValue: Value) =&gt; SelectOption&lt;Value&gt; | undefined"
+      },
+      "required": true
+    },
+    "highlightedOption": {
+      "type": { "name": "Value | null", "description": "Value | null" },
+      "required": true
+    },
+    "open": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "options": { "type": { "name": "Value[]", "description": "Value[]" }, "required": true },
+    "value": {
+      "type": {
+        "name": "SelectValue&lt;Value, Multiple&gt;",
+        "description": "SelectValue&lt;Value, Multiple&gt;"
+      },
+      "required": true
+    }
+  },
   "name": "useSelect",
   "filename": "/packages/mui-base/src/useSelect/useSelect.ts",
   "demos": "<ul><li><a href=\"/base/react-select/#hooks\">Unstyled Select</a></li></ul>"
diff --git a/docs/pages/base/api/use-tabs-list.json b/docs/pages/base/api/use-tabs-list.json
index b8e4327a6af97f..0b22563206d23a 100644
--- a/docs/pages/base/api/use-tabs-list.json
+++ b/docs/pages/base/api/use-tabs-list.json
@@ -3,30 +3,6 @@
     "ref": {
       "type": { "name": "React.Ref&lt;unknown&gt;", "description": "React.Ref&lt;unknown&gt;" },
       "required": true
-    },
-    "defaultValue": {
-      "type": { "name": "string | number | null", "description": "string | number | null" }
-    },
-    "direction": {
-      "type": {
-        "name": "&#39;ltr&#39; | &#39;rtl&#39;",
-        "description": "&#39;ltr&#39; | &#39;rtl&#39;"
-      }
-    },
-    "onChange": {
-      "type": {
-        "name": "(event: React.SyntheticEvent | null, value: string | number | null) =&gt; void",
-        "description": "(event: React.SyntheticEvent | null, value: string | number | null) =&gt; void"
-      }
-    },
-    "orientation": {
-      "type": {
-        "name": "&#39;horizontal&#39; | &#39;vertical&#39;",
-        "description": "&#39;horizontal&#39; | &#39;vertical&#39;"
-      }
-    },
-    "value": {
-      "type": { "name": "string | number | null", "description": "string | number | null" }
     }
   },
   "returnValue": {
diff --git a/docs/translations/api-docs/select-unstyled/select-unstyled.json b/docs/translations/api-docs/select-unstyled/select-unstyled.json
index 28647021ebd002..2503dfe0c92148 100644
--- a/docs/translations/api-docs/select-unstyled/select-unstyled.json
+++ b/docs/translations/api-docs/select-unstyled/select-unstyled.json
@@ -7,9 +7,9 @@
     "defaultValue": "The default selected value. Use when the component is not controlled.",
     "disabled": "If <code>true</code>, the select is disabled.",
     "getSerializedValue": "A function to convert the currently selected value to a string. Used to set a value of a hidden input associated with the select, so that the selected value can be posted with a form.",
-    "listboxId": "<code>id</code> attribute of the listbox element. Also used to derive the <code>id</code> attributes of options.",
+    "listboxId": "<code>id</code> attribute of the listbox element.",
     "listboxOpen": "Controls the open state of the select&#39;s listbox.",
-    "multiple": "If <code>true</code>, selecting multiple values is allowed.",
+    "multiple": "If <code>true</code>, selecting multiple values is allowed. This affects the type of the <code>value</code>, <code>defaultValue</code>, and <code>onChange</code> props.",
     "name": "Name of the element. For example used by the server to identify the fields in form submits. If the name is provided, the component will render a hidden input element that can be submitted to a server.",
     "onChange": "Callback fired when an option is selected.",
     "onListboxOpenChange": "Callback fired when the component requests to be opened. Use in controlled mode (see listboxOpen).",
diff --git a/docs/translations/api-docs/tab-panel-unstyled/tab-panel-unstyled.json b/docs/translations/api-docs/tab-panel-unstyled/tab-panel-unstyled.json
index e70bb5bc127f2e..e2889fd5aec6e6 100644
--- a/docs/translations/api-docs/tab-panel-unstyled/tab-panel-unstyled.json
+++ b/docs/translations/api-docs/tab-panel-unstyled/tab-panel-unstyled.json
@@ -5,7 +5,7 @@
     "component": "The component used for the root node. Either a string to use a HTML element or a component.",
     "slotProps": "The props used for each slot inside the TabPanel.",
     "slots": "The components used for each slot inside the TabPanel. Either a string to use a HTML element or a component. See <a href=\"#slots\">Slots API</a> below for more details.",
-    "value": "The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected."
+    "value": "The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected. If not provided, it will fall back to the index of the panel. It is recommended to explicitly provide it, as it&#39;s required for the tab panel to be rendered on the server."
   },
   "classDescriptions": {},
   "slotDescriptions": { "root": "The component that renders the root." }
diff --git a/docs/translations/api-docs/use-menu/use-menu.json b/docs/translations/api-docs/use-menu/use-menu.json
index 5dfdec77f9b666..fa42446d3bd622 100644
--- a/docs/translations/api-docs/use-menu/use-menu.json
+++ b/docs/translations/api-docs/use-menu/use-menu.json
@@ -1,6 +1,12 @@
 {
   "hookDescription": "",
-  "parametersDescriptions": {},
+  "parametersDescriptions": {
+    "defaultOpen": "If <code>true</code>, the menu will be initially open.",
+    "listboxId": "Id of the menu listbox.",
+    "listboxRef": "Ref of the menu listbox.",
+    "onOpenChange": "Callback fired when the menu is opened or closed.",
+    "open": "If <code>true</code>, the menu will be open.\nThis is the controlled equivalent of the <code>defaultOpen</code> parameter."
+  },
   "returnValueDescriptions": {
     "contextValue": "The value to be passed into the MenuProvider.",
     "dispatch": "Action dispatcher for the menu component.\nAllows to programmatically control the menu.",
diff --git a/docs/translations/api-docs/use-select/use-select.json b/docs/translations/api-docs/use-select/use-select.json
index e3eb65c6e43006..5255ca1ba6e134 100644
--- a/docs/translations/api-docs/use-select/use-select.json
+++ b/docs/translations/api-docs/use-select/use-select.json
@@ -1 +1,17 @@
-{ "hookDescription": "", "parametersDescriptions": {}, "returnValueDescriptions": {} }
+{
+  "hookDescription": "",
+  "parametersDescriptions": {},
+  "returnValueDescriptions": {
+    "buttonActive": "If <code>true</code>, the trigger button is active (pressed).",
+    "buttonFocusVisible": "If <code>true</code>, the trigger button has a visible focus.",
+    "contextValue": "A value to be passed to the <code>SelectProvider</code> component.",
+    "disabled": "If <code>true</code>, the select is disabled.",
+    "getButtonProps": "Resolver for the button slot's props.",
+    "getListboxProps": "Resolver for the listbox slot's props.",
+    "getOptionMetadata": "A function that returns the metadata of an option with a given value.",
+    "highlightedOption": "The value of the highlighted option.",
+    "open": "If <code>true</code>, the listbox is open.",
+    "options": "Values of all the registered options.",
+    "value": "The value of the selected option(s)."
+  }
+}
diff --git a/docs/translations/api-docs/use-tab-panel/use-tab-panel.json b/docs/translations/api-docs/use-tab-panel/use-tab-panel.json
index af377df9d4eba7..f1ba95b8808dd8 100644
--- a/docs/translations/api-docs/use-tab-panel/use-tab-panel.json
+++ b/docs/translations/api-docs/use-tab-panel/use-tab-panel.json
@@ -1,6 +1,7 @@
 {
   "hookDescription": "",
   "parametersDescriptions": {
+    "id": "The id of the TabPanel.",
     "value": "The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected."
   },
   "returnValueDescriptions": {
diff --git a/docs/translations/api-docs/use-tab/use-tab.json b/docs/translations/api-docs/use-tab/use-tab.json
index 7928a2917ba3b8..0f4fd4712898e2 100644
--- a/docs/translations/api-docs/use-tab/use-tab.json
+++ b/docs/translations/api-docs/use-tab/use-tab.json
@@ -1,8 +1,10 @@
 {
   "hookDescription": "",
   "parametersDescriptions": {
+    "disabled": "If <code>true</code>, the tab will be disabled.",
     "id": "The id of the tab.\nIf not provided, it will be automatically generated.",
     "onChange": "If <code>true</code>, the tab will be disabled.",
+    "onClick": "Callback fired when the tab is clicked.",
     "ref": "Ref to the DOM element associated with the tab.",
     "value": "The value of the tab.\nIt's used to associate the tab with a tab panel(s) with the same value.\nIf the value is not provided, it falls back to the position index."
   },
diff --git a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
index c45ecc6214a8dd..6f728d6f14478c 100644
--- a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
+++ b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
@@ -1,12 +1,12 @@
 {
   "hookDescription": "",
-  "parametersDescriptions": {},
+  "parametersDescriptions": { "ref": "Ref to the root element." },
   "returnValueDescriptions": {
     "contextValue": "The value to be passed to the TabListProvider above all the tabs.",
     "getRootProps": "Resolver for the root slot's props.",
-    "highlightedValue": "The value of the currently highlighted <code>Tab</code>.",
+    "highlightedValue": "The value of the currently highlighted tab.",
     "isRtl": "If <code>true</code>, it will indicate that the text's direction in right-to-left.",
     "orientation": "The component orientation (layout flow direction).",
-    "selectedValue": "The value of the currently selected <code>Tab</code>."
+    "selectedValue": "The value of the currently selected tab."
   }
 }
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
index b3741185472746..3fa0a786067860 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
@@ -45,6 +45,8 @@ const OptionUnstyled = React.forwardRef(function OptionUnstyled<TValue>(
   const optionRef = React.useRef<HTMLLIElement>(null);
   const combinedRef = useForkRef(optionRef, ref);
 
+  // If `label` is not explicitly provided, the `children` are used for convenience.
+  // This is used to populate the select's trigger with the selected option's label.
   const computedLabel =
     label ?? (typeof children === 'string' ? children : optionRef.current?.innerText);
 
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
index f593e9a0da6bfc..97bcbe4f1bb78a 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
@@ -285,7 +285,6 @@ SelectUnstyled.propTypes /* remove-proptypes */ = {
   getSerializedValue: PropTypes.func,
   /**
    * `id` attribute of the listbox element.
-   * Also used to derive the `id` attributes of options.
    */
   listboxId: PropTypes.string,
   /**
@@ -295,6 +294,7 @@ SelectUnstyled.propTypes /* remove-proptypes */ = {
   listboxOpen: PropTypes.bool,
   /**
    * If `true`, selecting multiple values is allowed.
+   * This affects the type of the `value`, `defaultValue`, and `onChange` props.
    *
    * @default false
    */
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
index 559256080d0fc6..6b277d3d86476d 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
@@ -41,7 +41,6 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
   ) => React.InputHTMLAttributes<HTMLInputElement>['value'];
   /**
    * `id` attribute of the listbox element.
-   * Also used to derive the `id` attributes of options.
    */
   listboxId?: string;
   /**
@@ -51,6 +50,7 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
   listboxOpen?: boolean;
   /**
    * If `true`, selecting multiple values is allowed.
+   * This affects the type of the `value`, `defaultValue`, and `onChange` props.
    *
    * @default false
    */
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
index 0690dcc75cd13b..6be6b331b83581 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.tsx
@@ -94,6 +94,8 @@ TabPanelUnstyled.propTypes /* remove-proptypes */ = {
   }),
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
+   * If not provided, it will fall back to the index of the panel.
+   * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
    */
   value: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
 } as any;
diff --git a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
index 0a722f7f79e629..b34825d803837a 100644
--- a/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
+++ b/packages/mui-base/src/TabPanelUnstyled/TabPanelUnstyled.types.ts
@@ -13,6 +13,8 @@ export interface TabPanelUnstyledOwnProps {
   className?: string;
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
+   * If not provided, it will fall back to the index of the panel.
+   * It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
    */
   value?: number | string;
   /**
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index dcb2c4290e69b0..a89fef3273cc3c 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -24,17 +24,16 @@ export type ListActionAddOnValue<ItemValue> = Simplify<
   Required<Pick<UseListParameters<ItemValue, any, any>, ListActionAddOnValueRequiredKeys>>
 >;
 
-export type ListReducerAction<ItemValue, State extends ListState<ItemValue>> = ListAction<
-  ItemValue,
-  State
-> & {
-  props: React.RefObject<ListActionAddOnValue<ItemValue>>;
-};
-
 export type ListActionAddOn<ItemValue> = {
   props: React.RefObject<ListActionAddOnValue<ItemValue>>;
 };
 
+export type ListReducerAction<ItemValue, State extends ListState<ItemValue>> = ListAction<
+  ItemValue,
+  State
+> &
+  ListActionAddOn<ItemValue>;
+
 export interface ListState<ItemValue> {
   /**
    * The item that is currently highlighted.
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 3f17c46ae9d9d7..05b04eb350b708 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -5,10 +5,27 @@ import { EventHandlers } from '../utils/types';
 import { MenuProviderValue } from './MenuProvider';
 
 export interface UseMenuParameters {
+  /**
+   * If `true`, the menu will be initially open.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /**
+   * If `true`, the menu will be open.
+   * This is the controlled equivalent of the `defaultOpen` parameter.
+   */
   open?: boolean;
+  /**
+   * Callback fired when the menu is opened or closed.
+   */
   onOpenChange?: (open: boolean) => void;
+  /**
+   * Id of the menu listbox.
+   */
   listboxId?: string;
+  /**
+   * Ref of the menu listbox.
+   */
   listboxRef?: React.Ref<any>;
 }
 
@@ -57,5 +74,8 @@ export type UseMenuListboxSlotProps<TOther = {}> = UseListRootSlotProps<
 };
 
 export interface MenuInternalState extends ListState<string> {
+  /**
+   * If `true`, the menu is open.
+   */
   open: boolean;
 }
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 480a3900366c8d..7c6d774738c35e 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -14,7 +14,7 @@ import {
   UseSelectButtonSlotProps,
   UseSelectListboxSlotProps,
   UseSelectParameters,
-  UseSelectResult,
+  UseSelectReturnValue,
 } from './useSelect.types';
 import useList, {
   listReducer,
@@ -41,7 +41,7 @@ import { SelectOption } from '../useOption/useOption.types';
  */
 function useSelect<TValue, Multiple extends boolean = false>(
   props: UseSelectParameters<TValue, Multiple>,
-): UseSelectResult<TValue, Multiple> {
+): UseSelectReturnValue<TValue, Multiple> {
   const {
     buttonRef: buttonRefProp,
     defaultOpen = false,
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 6a349525fae473..05e75693eac444 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -20,17 +20,49 @@ export interface SelectOptionDefinition<Value> {
 }
 
 export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
+  /**
+   * If `true`, the select will be initially open.
+   * @default false
+   */
   defaultOpen?: boolean;
+  /**
+   * The default selected value. Use when the component is not controlled.
+   */
   defaultValue?: SelectValue<TValue, Multiple>;
+  /**
+   * If `true`, the select is disabled.
+   * @default false
+   */
   disabled?: boolean;
+  /**
+   * The ref of the trigger button element.
+   */
   buttonRef?: React.Ref<Element>;
+  /**
+   * `id` attribute of the listbox element.
+   */
   listboxId?: string;
+  /**
+   * The ref of the listbox element.
+   */
   listboxRef?: React.Ref<Element>;
+  /**
+   * If `true`, selecting multiple values is allowed.
+   * This affects the type of the `value`, `defaultValue`, and `onChange` props.
+   *
+   * @default false
+   */
   multiple?: Multiple;
+  /**
+   * Callback fired when an option is selected.
+   */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
     value: SelectValue<TValue, Multiple>,
   ) => void;
+  /**
+   * Callback fired when an option is highlighted.
+   */
   onHighlightChange?: (
     e:
       | React.MouseEvent<Element, MouseEvent>
@@ -39,10 +71,32 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
       | null,
     highlighted: TValue | null,
   ) => void;
+  /**
+   * Callback fired when the listbox is opened or closed.
+   */
   onOpenChange?: (open: boolean) => void;
+  /**
+   * Controls the open state of the select's listbox.
+   * This is the controlled equivaled of the `defaultOpen` prop.
+   */
   open?: boolean;
+  /**
+   * An alternative way to specify the options.
+   * If this parameter is set, options defined as JSX children are ignored.
+   */
   options?: SelectOptionDefinition<TValue>[];
+  /**
+   * A function used to convert the option label to a string.
+   * It's useful when labels are elements and need to be converted to plain text
+   * to enable navigation using character keys on a keyboard.
+   *
+   * @default defaultOptionStringifier
+   */
   optionStringifier?: (option: SelectOption<TValue>) => string;
+  /**
+   * The selected value.
+   * Set to `null` to deselect all options.
+   */
   value?: SelectValue<TValue, Multiple>;
 };
 
@@ -68,22 +122,62 @@ export type UseSelectListboxSlotProps<TOther = {}> = UseListRootSlotProps<
   Omit<TOther, keyof UseSelectListboxSlotEventHandlers> & UseSelectListboxSlotEventHandlers
 >;
 
-export interface UseSelectResult<TValue, Multiple> {
+export interface UseSelectReturnValue<Value, Multiple> {
+  /**
+   * If `true`, the trigger button is active (pressed).
+   */
   buttonActive: boolean;
+  /**
+   * If `true`, the trigger button has a visible focus.
+   */
   buttonFocusVisible: boolean;
+  /**
+   * If `true`, the select is disabled.
+   */
   disabled: boolean;
-  getButtonProps: <TOther extends EventHandlers = {}>(
-    otherHandlers?: TOther,
-  ) => UseSelectButtonSlotProps<TOther>;
-  getListboxProps: <TOther extends EventHandlers = {}>(
-    otherHandlers?: TOther,
-  ) => UseSelectListboxSlotProps<TOther>;
-  getOptionMetadata: (option: TValue) => SelectOption<TValue> | undefined;
-  contextValue: SelectProviderValue<TValue>;
-  highlightedOption: TValue | null;
+  /**
+   * Resolver for the button slot's props.
+   * @param otherHandlers event handlers for the button slot
+   * @returns props that should be spread on the button slot
+   */
+  getButtonProps: <OtherHandlers extends EventHandlers = {}>(
+    otherHandlers?: OtherHandlers,
+  ) => UseSelectButtonSlotProps<OtherHandlers>;
+  /**
+   * Resolver for the listbox slot's props.
+   * @param otherHandlers event handlers for the listbox slot
+   * @returns props that should be spread on the listbox slot
+   */
+  getListboxProps: <OtherHandlers extends EventHandlers = {}>(
+    otherHandlers?: OtherHandlers,
+  ) => UseSelectListboxSlotProps<OtherHandlers>;
+  /**
+   * A function that returns the metadata of an option with a given value.
+   *
+   * @param optionValue the value of the option
+   * @returns
+   */
+  getOptionMetadata: (optionValue: Value) => SelectOption<Value> | undefined;
+  /**
+   * A value to be passed to the `SelectProvider` component.
+   */
+  contextValue: SelectProviderValue<Value>;
+  /**
+   * The value of the highlighted option.
+   */
+  highlightedOption: Value | null;
+  /**
+   * If `true`, the listbox is open.
+   */
   open: boolean;
-  options: TValue[];
-  value: SelectValue<TValue, Multiple>;
+  /**
+   * Values of all the registered options.
+   */
+  options: Value[];
+  /**
+   * The value of the selected option(s).
+   */
+  value: SelectValue<Value, Multiple>;
 }
 
 const ACTION_TYPES_BUTTON_CLICK = 'buttonClick';
diff --git a/packages/mui-base/src/useTab/useTab.types.ts b/packages/mui-base/src/useTab/useTab.types.ts
index 90998e8f523da0..a0dc1d621a029d 100644
--- a/packages/mui-base/src/useTab/useTab.types.ts
+++ b/packages/mui-base/src/useTab/useTab.types.ts
@@ -12,7 +12,13 @@ export interface UseTabParameters {
    * If `true`, the tab will be disabled.
    */
   onChange?: (event: React.SyntheticEvent, value: number | string) => void;
+  /**
+   * Callback fired when the tab is clicked.
+   */
   onClick?: React.MouseEventHandler;
+  /**
+   * If `true`, the tab will be disabled.
+   */
   disabled?: boolean;
   /**
    * The id of the tab.
diff --git a/packages/mui-base/src/useTabPanel/useTabPanel.types.ts b/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
index 1149f31866a1a3..26f0ed05084a1e 100644
--- a/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
+++ b/packages/mui-base/src/useTabPanel/useTabPanel.types.ts
@@ -1,4 +1,7 @@
 export interface UseTabPanelParameters {
+  /**
+   * The id of the TabPanel.
+   */
   id?: string;
   /**
    * The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected.
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 6ad2e53acf0322..59da70377e901b 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -1,7 +1,6 @@
 import * as React from 'react';
 import { useTabsContext } from '../TabsUnstyled';
 import {
-  TabsListContextValue,
   UseTabsListParameters,
   UseTabsListReturnValue,
   UseTabsListRootSlotProps,
@@ -17,8 +16,6 @@ import useList, {
   UseListParameters,
 } from '../useList';
 
-export const TabsListContext = React.createContext<TabsListContextValue | null>(null);
-
 /**
  *
  * Demos:
@@ -121,7 +118,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     [onSelected],
   );
 
-  const controlledState = React.useMemo(() => {
+  const controlledProps = React.useMemo(() => {
     if (value === undefined) {
       return {};
     }
@@ -136,7 +133,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     highlightedOption,
     selectedOptions,
   } = useList({
-    controlledProps: controlledState,
+    controlledProps,
     disabledItemsFocusable: !selectionFollowsFocus,
     focusManagement: 'DOM',
     getItemDomElement: getTabElement,
@@ -154,6 +151,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
       return;
     }
 
+    // when a value changes externally, the highlighted value should be synced to it
     if (value != null) {
       dispatch({
         type: ListActionTypes.setState,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.types.ts b/packages/mui-base/src/useTabsList/useTabsList.types.ts
index 37e5678b34c925..8c898b10462e3f 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.types.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.types.ts
@@ -1,23 +1,11 @@
 import * as React from 'react';
-import { ListItemState, UseListItemRootSlotProps } from '../useList';
-import { EventHandlers } from '../utils';
 import { TabsListProviderValue } from './TabsListProvider';
 
-export interface TabsListContextValue {
-  getTabProps: <TOther extends EventHandlers = {}>(
-    tabValue: string | number,
-    otherHandlers?: TOther,
-  ) => UseListItemRootSlotProps;
-  getTabState: (tabValue: string | number) => ListItemState;
-}
-
 export interface UseTabsListParameters {
+  /**
+   * Ref to the root element.
+   */
   ref: React.Ref<unknown>;
-  value?: string | number | null;
-  defaultValue?: string | number | null;
-  onChange?: (event: React.SyntheticEvent | null, value: string | number | null) => void;
-  orientation?: 'horizontal' | 'vertical';
-  direction?: 'ltr' | 'rtl';
 }
 
 export type UseTabsListRootSlotProps<TOther = {}> = TOther & {
@@ -31,7 +19,7 @@ export type UseTabsListRootSlotProps<TOther = {}> = TOther & {
 
 export interface UseTabsListReturnValue {
   /**
-   * The value of the currently highlighted `Tab`.
+   * The value of the currently highlighted tab.
    */
   highlightedValue: string | number | null;
   /**
@@ -45,7 +33,7 @@ export interface UseTabsListReturnValue {
    */
   orientation: 'horizontal' | 'vertical';
   /**
-   * The value of the currently selected `Tab`.
+   * The value of the currently selected tab.
    */
   selectedValue: string | number | null;
   /**
diff --git a/packages/mui-base/src/utils/useCompoundItem.ts b/packages/mui-base/src/utils/useCompoundItem.ts
index 62ca5cee0253b9..339120572bb34e 100644
--- a/packages/mui-base/src/utils/useCompoundItem.ts
+++ b/packages/mui-base/src/utils/useCompoundItem.ts
@@ -3,6 +3,11 @@ import { unstable_useEnhancedEffect as useEnhancedEffect } from '@mui/utils';
 import { CompoundComponentContext, CompoundComponentContextValue } from './useCompound';
 
 export interface UseCompoundItemReturnValue<Key> {
+  /**
+   * The unique key for the child component.
+   * If the id was provided to `useCompoundItem`, this will be the same value.
+   * Otherwise, this will be a value generated by the `missingKeyGenerator`.
+   */
   id: Key | undefined;
   /**
    * The 0-based index of the child component in the parent component's list of registered children.
@@ -20,6 +25,9 @@ export interface UseCompoundItemReturnValue<Key> {
  *
  * @param id A unique key for the child component. If the `id` is `undefined`, the registration logic will not run (this can sometimes be the case during SSR).
  * @param itemMetadata Arbitrary metadata to pass to the parent component. This should be a stable reference (e.g. a memoized object), to avoid unnecessary re-registrations.
+ * @param missingKeyGenerator A function that generates a unique id for the item.
+ *   It is called with the set of the ids of all the items that have already been registered.
+ *   Return `existingKeys.size` if you want to use the index of the new item as the id.
  *
  * @ignore - internal hook.
  */

From 6999645996b64766ddd6b22201bb9deafc7115b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 5 Apr 2023 11:49:10 +0200
Subject: [PATCH 29/49] Rename TValue to something more meaningful

---
 .../OptionUnstyled/OptionUnstyled.spec.tsx    |  4 +-
 .../src/OptionUnstyled/OptionUnstyled.tsx     |  8 +--
 .../OptionUnstyled/OptionUnstyled.types.ts    | 32 ++++-----
 .../SelectUnstyled/SelectUnstyled.spec.tsx    |  8 +--
 .../src/SelectUnstyled/SelectUnstyled.tsx     | 55 ++++++++--------
 .../SelectUnstyled/SelectUnstyled.types.ts    | 66 ++++++++++---------
 .../defaultOptionStringifier.ts               |  2 +-
 packages/mui-base/src/useSelect/useSelect.ts  | 51 +++++++-------
 .../mui-base/src/useSelect/useSelect.types.ts | 16 ++---
 9 files changed, 127 insertions(+), 115 deletions(-)
 rename packages/mui-base/src/{SelectUnstyled => useSelect}/defaultOptionStringifier.ts (77%)

diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.spec.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.spec.tsx
index 9a4dbd59179c05..dd1689c922be81 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.spec.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.spec.tsx
@@ -2,8 +2,8 @@ import * as React from 'react';
 import { expectType } from '@mui/types';
 import OptionUnstyled, { OptionUnstyledRootSlotProps } from '@mui/base/OptionUnstyled';
 
-const Root = React.forwardRef(function Root<TValue>(
-  props: OptionUnstyledRootSlotProps<TValue>,
+const Root = React.forwardRef(function Root<OptionValue>(
+  props: OptionUnstyledRootSlotProps<OptionValue>,
   ref: React.ForwardedRef<HTMLLIElement>,
 ) {
   const { ownerState, ...other } = props;
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
index 3fa0a786067860..728a796923bfaa 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.tsx
@@ -12,7 +12,7 @@ import { useSlotProps } from '../utils';
 import useOption from '../useOption';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
 
-function useUtilityClasses<TValue>(ownerState: OptionUnstyledOwnerState<TValue>) {
+function useUtilityClasses<OptionValue>(ownerState: OptionUnstyledOwnerState<OptionValue>) {
   const { disabled, highlighted, selected } = ownerState;
 
   const slots = {
@@ -25,8 +25,8 @@ function useUtilityClasses<TValue>(ownerState: OptionUnstyledOwnerState<TValue>)
 /**
  * An unstyled option to be used within a SelectUnstyled.
  */
-const OptionUnstyled = React.forwardRef(function OptionUnstyled<TValue>(
-  props: OptionUnstyledProps<TValue>,
+const OptionUnstyled = React.forwardRef(function OptionUnstyled<OptionValue>(
+  props: OptionUnstyledProps<OptionValue>,
   ref: React.ForwardedRef<HTMLLIElement>,
 ) {
   const {
@@ -57,7 +57,7 @@ const OptionUnstyled = React.forwardRef(function OptionUnstyled<TValue>(
     value,
   });
 
-  const ownerState: OptionUnstyledOwnerState<TValue> = {
+  const ownerState: OptionUnstyledOwnerState<OptionValue> = {
     ...props,
     disabled,
     highlighted,
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
index e90c6ee042805f..0f0470027b01ab 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.types.ts
@@ -5,11 +5,11 @@ import { SlotComponentProps } from '../utils';
 
 export interface OptionUnstyledRootSlotPropsOverrides {}
 
-export interface OptionUnstyledOwnProps<TValue> {
+export interface OptionUnstyledOwnProps<OptionValue> {
   /**
    * The value of the option.
    */
-  value: TValue;
+  value: OptionValue;
   children?: React.ReactNode;
   /**
    * If `true`, the option will be disabled.
@@ -25,7 +25,7 @@ export interface OptionUnstyledOwnProps<TValue> {
     root?: SlotComponentProps<
       'li',
       OptionUnstyledRootSlotPropsOverrides,
-      OptionUnstyledOwnerState<TValue>
+      OptionUnstyledOwnerState<OptionValue>
     >;
   };
   /**
@@ -49,45 +49,47 @@ export interface OptionUnstyledSlots {
   root?: React.ElementType;
 }
 
-export interface OptionUnstyledTypeMap<TValue, P = {}, D extends React.ElementType = 'li'> {
-  props: P & OptionUnstyledOwnProps<TValue>;
+export interface OptionUnstyledTypeMap<OptionValue, P = {}, D extends React.ElementType = 'li'> {
+  props: P & OptionUnstyledOwnProps<OptionValue>;
   defaultComponent: D;
 }
 
 export type OptionUnstyledProps<
-  TValue,
-  D extends React.ElementType = OptionUnstyledTypeMap<TValue>['defaultComponent'],
-> = OverrideProps<OptionUnstyledTypeMap<TValue, {}, D>, D> & {
+  OptionValue,
+  D extends React.ElementType = OptionUnstyledTypeMap<OptionValue>['defaultComponent'],
+> = OverrideProps<OptionUnstyledTypeMap<OptionValue, {}, D>, D> & {
   component?: D;
 };
 
 export interface OptionUnstyledType {
-  <TValue, C extends React.ElementType>(
+  <OptionValue, C extends React.ElementType>(
     props: {
       /**
        * The component used for the root node.
        * Either a string to use a HTML element or a component.
        */
       component: C;
-    } & OverrideProps<OptionUnstyledTypeMap<TValue>, C>,
+    } & OverrideProps<OptionUnstyledTypeMap<OptionValue>, C>,
+  ): JSX.Element | null;
+  <OptionValue>(
+    props: DefaultComponentProps<OptionUnstyledTypeMap<OptionValue>>,
   ): JSX.Element | null;
-  <TValue>(props: DefaultComponentProps<OptionUnstyledTypeMap<TValue>>): JSX.Element | null;
   propTypes?: any;
 }
 
-export type OptionUnstyledOwnerState<TValue> = Simplify<
-  OptionUnstyledOwnProps<TValue> & {
+export type OptionUnstyledOwnerState<OptionValue> = Simplify<
+  OptionUnstyledOwnProps<OptionValue> & {
     selected: boolean;
     highlighted: boolean;
     index: number;
   }
 >;
 
-export type OptionUnstyledRootSlotProps<TValue> = Simplify<
+export type OptionUnstyledRootSlotProps<OptionValue> = Simplify<
   UseOptionRootSlotProps & {
     children?: React.ReactNode;
     className: string;
     ref: React.Ref<HTMLLIElement>;
-    ownerState: OptionUnstyledOwnerState<TValue>;
+    ownerState: OptionUnstyledOwnerState<OptionValue>;
   }
 >;
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.spec.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.spec.tsx
index 1cf9f3287f3ea8..5495ead48ce009 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.spec.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.spec.tsx
@@ -27,15 +27,15 @@ const SelectUnstyledSlotPropsOverridesTest = (
   />
 );
 
-function CustomRoot<TValue extends {}, Multiple extends boolean>(
-  props: SelectUnstyledRootSlotProps<TValue, Multiple>,
+function CustomRoot<OptionValue extends {}, Multiple extends boolean>(
+  props: SelectUnstyledRootSlotProps<OptionValue, Multiple>,
 ) {
   const { ownerState, ...other } = props;
   return <div {...other} />;
 }
 
-function CustomPopper<TValue extends {}, Multiple extends boolean>(
-  props: SelectUnstyledPopperSlotProps<TValue, Multiple>,
+function CustomPopper<OptionValue extends {}, Multiple extends boolean>(
+  props: SelectUnstyledPopperSlotProps<OptionValue, Multiple>,
 ) {
   const { ownerState, ...other } = props;
   return <PopperUnstyled {...other} />;
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
index 97bcbe4f1bb78a..853787f7eb49bf 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.tsx
@@ -14,13 +14,13 @@ import { useSlotProps, WithOptionalOwnerState } from '../utils';
 import PopperUnstyled from '../PopperUnstyled';
 import composeClasses from '../composeClasses';
 import { getSelectUnstyledUtilityClass } from './selectUnstyledClasses';
-import defaultOptionStringifier from './defaultOptionStringifier';
+import defaultOptionStringifier from '../useSelect/defaultOptionStringifier';
 import { useClassNamesOverride } from '../utils/ClassNameConfigurator';
 import { SelectOption } from '../useOption';
 import SelectProvider from '../useSelect/SelectProvider';
 
-function defaultRenderValue<TValue>(
-  selectedOptions: SelectOption<TValue> | SelectOption<TValue>[] | null,
+function defaultRenderValue<OptionValue>(
+  selectedOptions: SelectOption<OptionValue> | SelectOption<OptionValue>[] | null,
 ) {
   if (Array.isArray(selectedOptions)) {
     return <React.Fragment>{selectedOptions.map((o) => o.label).join(', ')}</React.Fragment>;
@@ -29,8 +29,8 @@ function defaultRenderValue<TValue>(
   return selectedOptions?.label ?? '';
 }
 
-function defaultFormValueProvider<TValue>(
-  selectedOption: SelectOption<TValue> | SelectOption<TValue>[] | null,
+function defaultFormValueProvider<OptionValue>(
+  selectedOption: SelectOption<OptionValue> | SelectOption<OptionValue>[] | null,
 ) {
   if (Array.isArray(selectedOption)) {
     if (selectedOption.length === 0) {
@@ -92,9 +92,9 @@ function useUtilityClasses(ownerState: SelectUnstyledOwnerState<any, any>) {
  * - [SelectUnstyled API](https://mui.com/base/react-select/components-api/#select-unstyled)
  */
 const SelectUnstyled = React.forwardRef(function SelectUnstyled<
-  TValue extends {},
+  OptionValue extends {},
   Multiple extends boolean,
->(props: SelectUnstyledProps<TValue, Multiple>, forwardedRef: React.ForwardedRef<any>) {
+>(props: SelectUnstyledProps<OptionValue, Multiple>, forwardedRef: React.ForwardedRef<any>) {
   const {
     autoFocus,
     children,
@@ -117,7 +117,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     ...other
   } = props;
 
-  const renderValue: (option: SelectValue<SelectOption<TValue>, Multiple>) => React.ReactNode =
+  const renderValue: (option: SelectValue<SelectOption<OptionValue>, Multiple>) => React.ReactNode =
     renderValueProp ?? defaultRenderValue;
 
   const [buttonDefined, setButtonDefined] = React.useState(false);
@@ -164,7 +164,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     value: valueProp,
   });
 
-  const ownerState: SelectUnstyledOwnerState<TValue, Multiple> = {
+  const ownerState: SelectUnstyledOwnerState<OptionValue, Multiple> = {
     ...props,
     active: buttonActive,
     defaultListboxOpen,
@@ -178,7 +178,7 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
 
   const classes = useUtilityClasses(ownerState);
 
-  const buttonProps: WithOptionalOwnerState<SelectUnstyledRootSlotProps<TValue, Multiple>> =
+  const buttonProps: WithOptionalOwnerState<SelectUnstyledRootSlotProps<OptionValue, Multiple>> =
     useSlotProps({
       elementType: Button,
       getSlotProps: getButtonProps,
@@ -188,19 +188,20 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
       className: classes.root,
     });
 
-  const listboxProps: WithOptionalOwnerState<SelectUnstyledListboxSlotProps<TValue, Multiple>> =
-    useSlotProps({
-      elementType: ListboxRoot,
-      getSlotProps: getListboxProps,
-      externalSlotProps: slotProps.listbox,
-      additionalProps: {
-        ref: listboxRef,
-      },
-      ownerState,
-      className: classes.listbox,
-    });
+  const listboxProps: WithOptionalOwnerState<
+    SelectUnstyledListboxSlotProps<OptionValue, Multiple>
+  > = useSlotProps({
+    elementType: ListboxRoot,
+    getSlotProps: getListboxProps,
+    externalSlotProps: slotProps.listbox,
+    additionalProps: {
+      ref: listboxRef,
+    },
+    ownerState,
+    className: classes.listbox,
+  });
 
-  const popperProps: SelectUnstyledPopperSlotProps<TValue, Multiple> = useSlotProps({
+  const popperProps: SelectUnstyledPopperSlotProps<OptionValue, Multiple> = useSlotProps({
     elementType: Popper,
     externalSlotProps: slotProps.popper,
     additionalProps: {
@@ -214,14 +215,14 @@ const SelectUnstyled = React.forwardRef(function SelectUnstyled<
     className: classes.popper,
   });
 
-  let selectedOptionsMetadata: SelectValue<SelectOption<TValue>, Multiple>;
+  let selectedOptionsMetadata: SelectValue<SelectOption<OptionValue>, Multiple>;
   if (multiple) {
-    selectedOptionsMetadata = (value as TValue[])
+    selectedOptionsMetadata = (value as OptionValue[])
       .map((v) => getOptionMetadata(v))
-      .filter((o) => o !== undefined) as SelectValue<SelectOption<TValue>, Multiple>;
+      .filter((o) => o !== undefined) as SelectValue<SelectOption<OptionValue>, Multiple>;
   } else {
-    selectedOptionsMetadata = (getOptionMetadata(value as TValue) ?? null) as SelectValue<
-      SelectOption<TValue>,
+    selectedOptionsMetadata = (getOptionMetadata(value as OptionValue) ?? null) as SelectValue<
+      SelectOption<OptionValue>,
       Multiple
     >;
   }
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
index 6b277d3d86476d..a8da88681b3b72 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.types.ts
@@ -9,7 +9,7 @@ export interface SelectUnstyledRootSlotPropsOverrides {}
 export interface SelectUnstyledListboxSlotPropsOverrides {}
 export interface SelectUnstyledPopperSlotPropsOverrides {}
 
-export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends boolean> {
+export interface SelectUnstyledOwnProps<OptionValue extends {}, Multiple extends boolean> {
   /**
    * If `true`, the select element is focused during the first mount
    * @default false
@@ -25,7 +25,7 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
   /**
    * The default selected value. Use when the component is not controlled.
    */
-  defaultValue?: SelectValue<TValue, Multiple>;
+  defaultValue?: SelectValue<OptionValue, Multiple>;
   /**
    * If `true`, the select is disabled.
    * @default false
@@ -37,7 +37,7 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
    * so that the selected value can be posted with a form.
    */
   getSerializedValue?: (
-    option: SelectValue<SelectOption<TValue>, Multiple>,
+    option: SelectValue<SelectOption<OptionValue>, Multiple>,
   ) => React.InputHTMLAttributes<HTMLInputElement>['value'];
   /**
    * `id` attribute of the listbox element.
@@ -65,7 +65,7 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
    */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    value: SelectValue<TValue, Multiple>,
+    value: SelectValue<OptionValue, Multiple>,
   ) => void;
   /**
    * Callback fired when the component requests to be opened.
@@ -79,11 +79,11 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
    *
    * @default defaultOptionStringifier
    */
-  optionStringifier?: (option: SelectOption<TValue>) => string;
+  optionStringifier?: (option: SelectOption<OptionValue>) => string;
   /**
    * Function that customizes the rendering of the selected value.
    */
-  renderValue?: (option: SelectValue<SelectOption<TValue>, Multiple>) => React.ReactNode;
+  renderValue?: (option: SelectValue<SelectOption<OptionValue>, Multiple>) => React.ReactNode;
   /**
    * The props used for each slot inside the Input.
    * @default {}
@@ -92,17 +92,17 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
     root?: SlotComponentProps<
       'button',
       SelectUnstyledRootSlotPropsOverrides,
-      SelectUnstyledOwnerState<TValue, Multiple>
+      SelectUnstyledOwnerState<OptionValue, Multiple>
     >;
     listbox?: SlotComponentProps<
       'ul',
       SelectUnstyledListboxSlotPropsOverrides,
-      SelectUnstyledOwnerState<TValue, Multiple>
+      SelectUnstyledOwnerState<OptionValue, Multiple>
     >;
     popper?: SlotComponentProps<
       typeof PopperUnstyled,
       SelectUnstyledPopperSlotPropsOverrides,
-      SelectUnstyledOwnerState<TValue, Multiple>
+      SelectUnstyledOwnerState<OptionValue, Multiple>
     >;
   };
   /**
@@ -110,15 +110,15 @@ export interface SelectUnstyledOwnProps<TValue extends {}, Multiple extends bool
    * Either a string to use a HTML element or a component.
    * @default {}
    */
-  slots?: SelectUnstyledSlots<TValue, Multiple>;
+  slots?: SelectUnstyledSlots<OptionValue, Multiple>;
   /**
    * The selected value.
    * Set to `null` to deselect all options.
    */
-  value?: SelectValue<TValue, Multiple>;
+  value?: SelectValue<OptionValue, Multiple>;
 }
 
-export interface SelectUnstyledSlots<TValue extends {}, Multiple extends boolean> {
+export interface SelectUnstyledSlots<OptionValue extends {}, Multiple extends boolean> {
   /**
    * The component that renders the root.
    * @default 'button'
@@ -133,74 +133,80 @@ export interface SelectUnstyledSlots<TValue extends {}, Multiple extends boolean
    * The component that renders the popper.
    * @default PopperUnstyled
    */
-  popper?: React.ComponentType<SelectUnstyledPopperSlotProps<TValue, Multiple>>;
+  popper?: React.ComponentType<SelectUnstyledPopperSlotProps<OptionValue, Multiple>>;
 }
 
 export interface SelectUnstyledTypeMap<
-  TValue extends {},
+  OptionValue extends {},
   Multiple extends boolean,
   P = {},
   D extends React.ElementType = 'button',
 > {
-  props: P & SelectUnstyledOwnProps<TValue, Multiple>;
+  props: P & SelectUnstyledOwnProps<OptionValue, Multiple>;
   defaultComponent: D;
 }
 
 export type SelectUnstyledProps<
-  TValue extends {},
+  OptionValue extends {},
   Multiple extends boolean,
-  D extends React.ElementType = SelectUnstyledTypeMap<TValue, Multiple>['defaultComponent'],
-> = OverrideProps<SelectUnstyledTypeMap<TValue, Multiple, {}, D>, D> & {
+  D extends React.ElementType = SelectUnstyledTypeMap<OptionValue, Multiple>['defaultComponent'],
+> = OverrideProps<SelectUnstyledTypeMap<OptionValue, Multiple, {}, D>, D> & {
   component?: D;
 };
 
 // OverridableComponent cannot be used below as SelectUnstyled's props are generic.
 export interface SelectUnstyledType {
-  <TValue extends {}, C extends React.ElementType, Multiple extends boolean = false>(
+  <OptionValue extends {}, C extends React.ElementType, Multiple extends boolean = false>(
     props: {
       /**
        * The component used for the root node.
        * Either a string to use a HTML element or a component.
        */
       component: C;
-    } & OverrideProps<SelectUnstyledTypeMap<TValue, Multiple>, C>,
+    } & OverrideProps<SelectUnstyledTypeMap<OptionValue, Multiple>, C>,
   ): JSX.Element | null;
-  <TValue extends {}, Multiple extends boolean = false>(
-    props: DefaultComponentProps<SelectUnstyledTypeMap<TValue, Multiple>>,
+  <OptionValue extends {}, Multiple extends boolean = false>(
+    props: DefaultComponentProps<SelectUnstyledTypeMap<OptionValue, Multiple>>,
   ): JSX.Element | null;
   propTypes?: any;
 }
 
-export interface SelectUnstyledOwnerState<TValue extends {}, Multiple extends boolean>
-  extends SelectUnstyledOwnProps<TValue, Multiple> {
+export interface SelectUnstyledOwnerState<OptionValue extends {}, Multiple extends boolean>
+  extends SelectUnstyledOwnProps<OptionValue, Multiple> {
   active: boolean;
   disabled: boolean;
   focusVisible: boolean;
   open: boolean;
 }
 
-export type SelectUnstyledRootSlotProps<TValue extends {}, Multiple extends boolean> = Simplify<
+export type SelectUnstyledRootSlotProps<
+  OptionValue extends {},
+  Multiple extends boolean,
+> = Simplify<
   UseSelectButtonSlotProps & {
     className?: string;
     children?: React.ReactNode;
-    ownerState: SelectUnstyledOwnerState<TValue, Multiple>;
+    ownerState: SelectUnstyledOwnerState<OptionValue, Multiple>;
   }
 >;
 
-export type SelectUnstyledListboxSlotProps<TValue extends {}, Multiple extends boolean> = Simplify<
+export type SelectUnstyledListboxSlotProps<
+  OptionValue extends {},
+  Multiple extends boolean,
+> = Simplify<
   UseSelectListboxSlotProps & {
     className?: string;
     children?: React.ReactNode;
-    ownerState: SelectUnstyledOwnerState<TValue, Multiple>;
+    ownerState: SelectUnstyledOwnerState<OptionValue, Multiple>;
   }
 >;
 
-export type SelectUnstyledPopperSlotProps<TValue extends {}, Multiple extends boolean> = {
+export type SelectUnstyledPopperSlotProps<OptionValue extends {}, Multiple extends boolean> = {
   anchorEl: PopperUnstyledProps['anchorEl'];
   children?: PopperUnstyledProps['children'];
   className?: string;
   keepMounted: PopperUnstyledProps['keepMounted'];
   open: boolean;
-  ownerState: SelectUnstyledOwnerState<TValue, Multiple>;
+  ownerState: SelectUnstyledOwnerState<OptionValue, Multiple>;
   placement: PopperUnstyledProps['placement'];
 };
diff --git a/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts b/packages/mui-base/src/useSelect/defaultOptionStringifier.ts
similarity index 77%
rename from packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts
rename to packages/mui-base/src/useSelect/defaultOptionStringifier.ts
index 6d193aa0533d3f..e30bf637096468 100644
--- a/packages/mui-base/src/SelectUnstyled/defaultOptionStringifier.ts
+++ b/packages/mui-base/src/useSelect/defaultOptionStringifier.ts
@@ -1,6 +1,6 @@
 import { SelectOption } from '../useOption';
 
-const defaultOptionStringifier = <TValue>(option: SelectOption<TValue>) => {
+const defaultOptionStringifier = <OptionValue>(option: SelectOption<OptionValue>) => {
   const { label, value } = option;
   if (typeof label === 'string') {
     return label;
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 7c6d774738c35e..33c35efe660a6a 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -24,7 +24,7 @@ import useList, {
   ListActionAddOn,
 } from '../useList';
 import { EventHandlers } from '../utils/types';
-import defaultOptionStringifier from '../SelectUnstyled/defaultOptionStringifier';
+import defaultOptionStringifier from './defaultOptionStringifier';
 import { SelectProviderValue } from './SelectProvider';
 import { useCompoundParent } from '../utils/useCompound';
 import { SelectOption } from '../useOption/useOption.types';
@@ -39,9 +39,9 @@ import { SelectOption } from '../useOption/useOption.types';
  *
  * - [useSelect API](https://mui.com/base/react-select/hooks-api/#use-select)
  */
-function useSelect<TValue, Multiple extends boolean = false>(
-  props: UseSelectParameters<TValue, Multiple>,
-): UseSelectReturnValue<TValue, Multiple> {
+function useSelect<OptionValue, Multiple extends boolean = false>(
+  props: UseSelectParameters<OptionValue, Multiple>,
+): UseSelectReturnValue<OptionValue, Multiple> {
   const {
     buttonRef: buttonRefProp,
     defaultOpen = false,
@@ -65,24 +65,26 @@ function useSelect<TValue, Multiple extends boolean = false>(
   const listboxRef = React.useRef<HTMLElement | null>(null);
   const listboxId = useId(listboxIdProp);
 
-  let defaultValue: TValue[] | undefined;
+  let defaultValue: OptionValue[] | undefined;
   if (valueProp === undefined && defaultValueProp === undefined) {
     defaultValue = [];
   } else if (defaultValueProp !== undefined) {
-    defaultValue = multiple ? (defaultValueProp as TValue[]) : [defaultValueProp as TValue];
+    defaultValue = multiple
+      ? (defaultValueProp as OptionValue[])
+      : [defaultValueProp as OptionValue];
   }
 
   const value = React.useMemo(() => {
     if (valueProp !== undefined) {
-      return multiple ? (valueProp as TValue[]) : [valueProp as TValue];
+      return multiple ? (valueProp as OptionValue[]) : [valueProp as OptionValue];
     }
 
     return undefined;
   }, [valueProp, multiple]);
 
   const { subitems, contextValue: compoundComponentContextValue } = useCompoundParent<
-    TValue,
-    SelectOption<TValue>
+    OptionValue,
+    SelectOption<OptionValue>
   >();
 
   const options = React.useMemo(() => {
@@ -125,9 +127,9 @@ function useSelect<TValue, Multiple extends boolean = false>(
 
   const stateReducer = React.useCallback(
     (
-      state: SelectInternalState<TValue>,
-      action: (ListAction<TValue, SelectInternalState<TValue>> | SelectAction) &
-        ListActionAddOn<TValue>,
+      state: SelectInternalState<OptionValue>,
+      action: (ListAction<OptionValue, SelectInternalState<OptionValue>> | SelectAction) &
+        ListActionAddOn<OptionValue>,
     ) => {
       const { open } = state;
 
@@ -160,9 +162,10 @@ function useSelect<TValue, Multiple extends boolean = false>(
           break;
       }
 
-      const newState: SelectInternalState<TValue> = listReducer(
+      const newState: SelectInternalState<OptionValue> = listReducer(
         state,
-        action as ListAction<TValue, SelectInternalState<TValue>> & ListActionAddOn<TValue>,
+        action as ListAction<OptionValue, SelectInternalState<OptionValue>> &
+          ListActionAddOn<OptionValue>,
       );
 
       switch (action.type) {
@@ -240,7 +243,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
   const optionValues = React.useMemo(() => Array.from(options.keys()), [options]);
 
   const isItemDisabled = React.useCallback(
-    (valueToCheck: TValue) => {
+    (valueToCheck: OptionValue) => {
       const option = options.get(valueToCheck);
       return option?.disabled ?? false;
     },
@@ -248,7 +251,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
   );
 
   const stringifyOption = React.useCallback(
-    (valueToCheck: TValue) => {
+    (valueToCheck: OptionValue) => {
       const option = options.get(valueToCheck);
       if (!option) {
         return '';
@@ -268,8 +271,8 @@ function useSelect<TValue, Multiple extends boolean = false>(
   );
 
   const useListboxParameters: UseListParameters<
-    TValue,
-    SelectInternalState<TValue>,
+    OptionValue,
+    SelectInternalState<OptionValue>,
     SelectAction
   > = {
     getInitialState: () => ({
@@ -283,9 +286,9 @@ function useSelect<TValue, Multiple extends boolean = false>(
     listRef: handleListboxRef,
     onChange: (e, newValues) => {
       if (multiple) {
-        onChange?.(e, newValues as SelectValue<TValue, Multiple>);
+        onChange?.(e, newValues as SelectValue<OptionValue, Multiple>);
       } else {
-        onChange?.(e, (newValues[0] ?? null) as SelectValue<TValue, Multiple>);
+        onChange?.(e, (newValues[0] ?? null) as SelectValue<OptionValue, Multiple>);
       }
     },
     onHighlightChange: (e, newValue) => {
@@ -418,7 +421,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
   };
 
   const getOptionMetadata = React.useCallback(
-    (optionValue: TValue) => options.get(optionValue),
+    (optionValue: OptionValue) => options.get(optionValue),
     [options],
   );
 
@@ -442,7 +445,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
     open,
   });
 
-  const contextValue: SelectProviderValue<TValue> = React.useMemo(
+  const contextValue: SelectProviderValue<OptionValue> = React.useMemo(
     () => ({
       ...listContextValue,
       ...compoundComponentContextValue,
@@ -461,7 +464,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
       contextValue,
       open,
       options: optionValues,
-      value: selectedOptions as SelectValue<TValue, Multiple>,
+      value: selectedOptions as SelectValue<OptionValue, Multiple>,
       highlightedOption,
     };
   }
@@ -477,7 +480,7 @@ function useSelect<TValue, Multiple extends boolean = false>(
     open,
     options: optionValues,
     value: (selectedOptions.length > 0 ? selectedOptions[0] : null) as SelectValue<
-      TValue,
+      OptionValue,
       Multiple
     >,
     highlightedOption,
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 05e75693eac444..3eab7c4925a85e 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -19,7 +19,7 @@ export interface SelectOptionDefinition<Value> {
   label: string;
 }
 
-export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
+export type UseSelectParameters<OptionValue, Multiple extends boolean = false> = {
   /**
    * If `true`, the select will be initially open.
    * @default false
@@ -28,7 +28,7 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
   /**
    * The default selected value. Use when the component is not controlled.
    */
-  defaultValue?: SelectValue<TValue, Multiple>;
+  defaultValue?: SelectValue<OptionValue, Multiple>;
   /**
    * If `true`, the select is disabled.
    * @default false
@@ -58,7 +58,7 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
    */
   onChange?: (
     e: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null,
-    value: SelectValue<TValue, Multiple>,
+    value: SelectValue<OptionValue, Multiple>,
   ) => void;
   /**
    * Callback fired when an option is highlighted.
@@ -69,7 +69,7 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
       | React.KeyboardEvent<Element>
       | React.FocusEvent<Element, Element>
       | null,
-    highlighted: TValue | null,
+    highlighted: OptionValue | null,
   ) => void;
   /**
    * Callback fired when the listbox is opened or closed.
@@ -84,7 +84,7 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
    * An alternative way to specify the options.
    * If this parameter is set, options defined as JSX children are ignored.
    */
-  options?: SelectOptionDefinition<TValue>[];
+  options?: SelectOptionDefinition<OptionValue>[];
   /**
    * A function used to convert the option label to a string.
    * It's useful when labels are elements and need to be converted to plain text
@@ -92,12 +92,12 @@ export type UseSelectParameters<TValue, Multiple extends boolean = false> = {
    *
    * @default defaultOptionStringifier
    */
-  optionStringifier?: (option: SelectOption<TValue>) => string;
+  optionStringifier?: (option: SelectOption<OptionValue>) => string;
   /**
    * The selected value.
    * Set to `null` to deselect all options.
    */
-  value?: SelectValue<TValue, Multiple>;
+  value?: SelectValue<OptionValue, Multiple>;
 };
 
 interface UseSelectButtonSlotEventHandlers {
@@ -200,6 +200,6 @@ export interface ButtonArrowKeyDownAction {
 
 export type SelectAction = ButtonClickAction | ButtonArrowKeyDownAction;
 
-export interface SelectInternalState<TValue> extends ListState<TValue> {
+export interface SelectInternalState<OptionValue> extends ListState<OptionValue> {
   open: boolean;
 }

From 422e0bf799b77e18624be428adef2cdf142e68b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Wed, 5 Apr 2023 11:49:24 +0200
Subject: [PATCH 30/49] Revert useLatest

---
 packages/mui-base/src/utils/useLatest.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/mui-base/src/utils/useLatest.ts b/packages/mui-base/src/utils/useLatest.ts
index 5d21dd459a1512..dd542da03684c4 100644
--- a/packages/mui-base/src/utils/useLatest.ts
+++ b/packages/mui-base/src/utils/useLatest.ts
@@ -15,7 +15,6 @@ import * as React from 'react';
  */
 export default function useLatest<T>(value: T, deps?: React.DependencyList) {
   const ref = React.useRef<T>(value);
-  ref.current = value;
 
   React.useEffect(() => {
     ref.current = value;

From 15c8ae1356fa8cf2d50284be42d9adf81a993829 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 09:56:16 +0200
Subject: [PATCH 31/49] Wrap useStateChangeDetection's parameters in an object

---
 .../src/utils/useControllableReducer.ts       | 61 ++++++++++++-------
 1 file changed, 38 insertions(+), 23 deletions(-)

diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
index 5257c4645990c9..791fe69ba3c34c 100644
--- a/packages/mui-base/src/utils/useControllableReducer.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -29,24 +29,39 @@ function getControlledState<State>(internalState: State, controlledProps: Partia
   return augmentedState;
 }
 
-/**
- * Triggers the change event handler when reducer returns changed state.
- *
- * @param nextState The next state returned by the reducer.
- * @param internalPreviousState The previous state. If the component is controlled, this is merged with the props to determine the final state.
- * @param stateComparers Comparers for each state item. If a state item has a corresponding comparer, it will be used to determine if the state has changed.
- * @param onStateChange The change event handler.
- * @param controlledProps The external props used to override the state items.
- * @param lastActionRef The last action that was dispatched.
- */
+interface UseStateChangeDetectionParameters<State extends {}> {
+  /**
+   * The next state returned by the reducer.
+   */
+  nextState: State;
+  /**
+   * The initial state.
+   */
+  initialState: State;
+  /**
+   * Comparers for each state item. If a state item has a corresponding comparer, it will be used to determine if the state has changed.
+   */
+  stateComparers: StateComparers<State>;
+  /**
+   * The function called when the state has changed.
+   */
+  onStateChange: StateChangeCallback<State>;
+  /**
+   * The external props used to override the state items.
+   */
+  controlledProps: Partial<State>;
+  /**
+   * The last action that was dispatched.
+   */
+  lastActionRef: React.MutableRefObject<ControllableReducerAction | null>;
+}
+
 function useStateChangeDetection<State extends {}>(
-  nextState: State,
-  initialState: State,
-  stateComparers: StateComparers<State>,
-  onStateChange: StateChangeCallback<State>,
-  controlledProps: Partial<State>,
-  lastActionRef: React.MutableRefObject<ControllableReducerAction | null>,
+  parameters: UseStateChangeDetectionParameters<State>,
 ) {
+  const { nextState, initialState, stateComparers, onStateChange, controlledProps, lastActionRef } =
+    parameters;
+
   const internalPreviousStateRef = React.useRef<State>(initialState);
 
   React.useEffect(() => {
@@ -118,7 +133,7 @@ export default function useControllableReducer<
 >(
   parameters: ControllableReducerParameters<State, Action, ActionAddOn>,
 ): [State, (action: Action) => void] {
-  const actionRef = React.useRef<Action | null>(null);
+  const lastActionRef = React.useRef<Action | null>(null);
 
   const {
     reducer,
@@ -132,7 +147,7 @@ export default function useControllableReducer<
   // The reducer that is passed to React.useReducer is wrapped with a function that augments the state with controlled values.
   const reducerWithControlledState = React.useCallback(
     (state: State, action: Action & ActionAddOn) => {
-      actionRef.current = action;
+      lastActionRef.current = action;
       const controlledState = getControlledState(state, controlledProps);
       return reducer(controlledState, action);
     },
@@ -152,14 +167,14 @@ export default function useControllableReducer<
     [actionAddOn],
   );
 
-  useStateChangeDetection<State>(
+  useStateChangeDetection<State>({
     nextState,
     initialState,
-    stateComparers ?? EMPTY_OBJECT,
-    onStateChange ?? NOOP,
+    stateComparers: stateComparers ?? EMPTY_OBJECT,
+    onStateChange: onStateChange ?? NOOP,
     controlledProps,
-    actionRef,
-  );
+    lastActionRef,
+  });
 
   return [getControlledState(nextState, controlledProps), dispatchWithAddOn];
 }

From 10ace6da15dc34dee16f75dd4db134cb4cfba78f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 14:05:31 +0200
Subject: [PATCH 32/49] listReducer keyboard navigation tests and fixes

---
 .../mui-base/src/useList/listReducer.test.ts  | 525 +++++++++++++-----
 packages/mui-base/src/useList/listReducer.ts  |  15 +-
 2 files changed, 396 insertions(+), 144 deletions(-)

diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index c1de2d029400ee..525f0920a37152 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -153,6 +153,35 @@ describe('listReducer', () => {
       expect(result.selectedValues).to.deep.equal(['one', 'two']);
     });
 
+    it('limits the selection to specified number of items', () => {
+      const state: ListState<string> = {
+        highlightedValue: 'three',
+        selectedValues: ['one', 'two'],
+      };
+
+      const action: ListReducerAction<string, ListState<string>> = {
+        type: ListActionTypes.itemClick,
+        event: {} as any,
+        item: 'three',
+        props: {
+          current: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            selectionLimit: 2,
+          },
+        },
+      };
+
+      const result = listReducer(state, action);
+      expect(result.selectedValues).to.deep.equal(['two', 'three']);
+    });
+
     it('remove the clicked value from the selection if selectionLimit is not set and it was selected already', () => {
       const state: ListState<string> = {
         highlightedValue: 'three',
@@ -184,146 +213,362 @@ describe('listReducer', () => {
   });
 
   describe('action: keyDown', () => {
-    describe('Home key is pressed', () => {
-      it('highlights the first non-disabled option if the first is disabled', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string, ListState<string>> = {
-          type: ListActionTypes.keyDown,
-          key: 'Home',
-          event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three', 'four', 'five'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: (_, index) => index === 0,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              selectionLimit: null,
-            },
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('two');
-      });
-    });
-
-    describe('End key is pressed', () => {
-      it('highlights the last non-disabled option if the last is disabled', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string, ListState<string>> = {
-          type: ListActionTypes.keyDown,
-          key: 'End',
-          event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three', 'four', 'five'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: (_, index) => index === 4,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              selectionLimit: null,
+    interface KeydownTestCase {
+      name: string;
+      key: string;
+      initialHighlightedItem: string | null;
+      disabledItemFocusable: boolean;
+      disabledItems: string[];
+      disableListWrap: boolean;
+      expected: string | null;
+    }
+
+    const testCases: KeydownTestCase[] = [
+      {
+        name: 'happy path',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'highlights the first enabled item',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1'],
+        disableListWrap: false,
+        expected: '2',
+      },
+      {
+        name: 'highlights the first enabled item',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2'],
+        disableListWrap: false,
+        expected: '3',
+      },
+      {
+        name: 'highlights the first item even if it is disabled',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1'],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'all disabled',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: null,
+      },
+      {
+        name: 'all disabled but focusable',
+        key: 'Home',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'happy path',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        name: 'highlights the last enabled item',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['5'],
+        disableListWrap: false,
+        expected: '4',
+      },
+      {
+        name: 'highlights the last enabled item',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['4', '5'],
+        disableListWrap: false,
+        expected: '3',
+      },
+      {
+        name: 'highlights the last item even if it is disabled',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['5'],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        name: 'all disabled',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: null,
+      },
+      {
+        name: 'all disabled but focusable',
+        key: 'End',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        name: 'happy path',
+        key: 'ArrowDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'happy path',
+        key: 'ArrowDown',
+        initialHighlightedItem: '1',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '2',
+      },
+      {
+        name: 'skips the disabled item',
+        key: 'ArrowDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1'],
+        disableListWrap: false,
+        expected: '2',
+      },
+      {
+        name: 'skips multiple disabled items',
+        key: 'ArrowDown',
+        initialHighlightedItem: '1',
+        disabledItemFocusable: false,
+        disabledItems: ['2', '3'],
+        disableListWrap: false,
+        expected: '4',
+      },
+      {
+        name: 'skips the disabled items and wraps around',
+        key: 'ArrowDown',
+        initialHighlightedItem: '3',
+        disabledItemFocusable: false,
+        disabledItems: ['1', '4', '5'],
+        disableListWrap: false,
+        expected: '2',
+      },
+      {
+        name: 'focuses the disabled item',
+        key: 'ArrowDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1'],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'does not wrap around',
+        key: 'ArrowDown',
+        initialHighlightedItem: '5',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: true,
+        expected: '5',
+      },
+      {
+        name: 'remains on the same item when all the next are disabled',
+        key: 'ArrowDown',
+        initialHighlightedItem: '3',
+        disabledItemFocusable: false,
+        disabledItems: ['4', '5'],
+        disableListWrap: true,
+        expected: '3',
+      },
+      {
+        name: 'all disabled',
+        key: 'ArrowDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: null,
+      },
+      {
+        name: 'all disabled but focusable',
+        key: 'ArrowDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'happy path',
+        key: 'ArrowUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        name: 'happy path',
+        key: 'ArrowUp',
+        initialHighlightedItem: '2',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        name: 'skips the disabled item',
+        key: 'ArrowUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['5'],
+        disableListWrap: false,
+        expected: '4',
+      },
+      {
+        name: 'skips multiple disabled items',
+        key: 'ArrowUp',
+        initialHighlightedItem: '1',
+        disabledItemFocusable: false,
+        disabledItems: ['4', '5'],
+        disableListWrap: false,
+        expected: '3',
+      },
+      {
+        name: 'skips the disabled items and wraps around',
+        key: 'ArrowUp',
+        initialHighlightedItem: '2',
+        disabledItemFocusable: false,
+        disabledItems: ['1', '4', '5'],
+        disableListWrap: false,
+        expected: '3',
+      },
+      {
+        name: 'focuses the disabled item',
+        key: 'ArrowUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['5'],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        name: 'does not wrap around',
+        key: 'ArrowUp',
+        initialHighlightedItem: '1',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: true,
+        expected: '1',
+      },
+      {
+        name: 'remains on the same item when all the previous are disabled',
+        key: 'ArrowUp',
+        initialHighlightedItem: '3',
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2'],
+        disableListWrap: true,
+        expected: '3',
+      },
+      {
+        name: 'all disabled',
+        key: 'ArrowUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: null,
+      },
+      {
+        name: 'all disabled but focusable',
+        key: 'ArrowUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: true,
+        disabledItems: ['1', '2', '3', '4', '5'],
+        disableListWrap: false,
+        expected: '5',
+      },
+    ];
+
+    testCases.forEach((spec: KeydownTestCase) => {
+      describe(`given initialHighlightedItem: '${
+        spec.initialHighlightedItem
+      }', disabledItemsFocusable: ${spec.disabledItemFocusable}, disableListWrap: ${
+        spec.disableListWrap
+      }, disabledItems: [${spec.disabledItems.join()}]`, () => {
+        it(`${spec.name}: should highlight the '${spec.expected}' item after the ${spec.key} is pressed`, () => {
+          const state: ListState<string> = {
+            highlightedValue: spec.initialHighlightedItem,
+            selectedValues: [],
+          };
+
+          const action: ListReducerAction<string, ListState<string>> = {
+            type: ListActionTypes.keyDown,
+            key: spec.key,
+            event: null as any, // not relevant
+            props: {
+              current: {
+                items: ['1', '2', '3', '4', '5'],
+                disableListWrap: spec.disableListWrap,
+                disabledItemsFocusable: spec.disabledItemFocusable,
+                focusManagement: 'activeDescendant',
+                isItemDisabled: (item) => spec.disabledItems.includes(item),
+                itemComparer: (o, v) => o === v,
+                itemStringifier: (option) => option,
+                orientation: 'vertical',
+                selectionLimit: null,
+              },
             },
-          },
-        };
+          };
 
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('four');
+          const result = listReducer(state, action);
+          expect(result.highlightedValue).to.equal(spec.expected);
+        });
       });
     });
 
-    describe('ArrowUp key is pressed', () => {
-      it('wraps the highlight around omitting disabled items', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string, ListState<string>> = {
-          type: ListActionTypes.keyDown,
-          key: 'ArrowUp',
-          event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three', 'four', 'five'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: (_, index) => index === 0 || index === 4,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              selectionLimit: null,
-            },
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('four');
-      });
-    });
-
-    describe('ArrowDown key is pressed', () => {
-      it('wraps the highlight around omitting disabled items', () => {
-        const state: ListState<string> = {
-          highlightedValue: null,
-          selectedValues: [],
-        };
-
-        const action: ListReducerAction<string, ListState<string>> = {
-          type: ListActionTypes.keyDown,
-          key: 'ArrowDown',
-          event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three', 'four', 'five'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: (_, index) => index === 0 || index === 4,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              selectionLimit: null,
-            },
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal('two');
-      });
-
-      it('does not highlight any option if all are disabled', () => {
+    describe('Enter key is pressed', () => {
+      it('selects the highlighted option', () => {
         const state: ListState<string> = {
-          highlightedValue: null,
+          highlightedValue: 'two',
           selectedValues: [],
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
           type: ListActionTypes.keyDown,
-          key: 'ArrowDown',
+          key: 'Enter',
           event: {} as any,
           props: {
             current: {
-              items: ['one', 'two', 'three', 'four', 'five'],
+              items: ['one', 'two', 'three'],
               disableListWrap: false,
               disabledItemsFocusable: false,
               focusManagement: 'activeDescendant',
-              isItemDisabled: () => true,
+              isItemDisabled: () => false,
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
@@ -333,15 +578,13 @@ describe('listReducer', () => {
         };
 
         const result = listReducer(state, action);
-        expect(result.highlightedValue).to.equal(null);
+        expect(result.selectedValues).to.deep.equal(['two']);
       });
-    });
 
-    describe('Enter key is pressed', () => {
-      it('selects the highlighted option', () => {
+      it('replaces the selectedValues with the highlighted value if selectionLimit = 1', () => {
         const state: ListState<string> = {
           highlightedValue: 'two',
-          selectedValues: [],
+          selectedValues: ['one'],
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
@@ -358,7 +601,7 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
-              selectionLimit: null,
+              selectionLimit: 1,
             },
           },
         };
@@ -367,7 +610,7 @@ describe('listReducer', () => {
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
-      it('replaces the selectedValues with the highlighted value if selectionLimit = 1', () => {
+      it('add the highlighted value to the selection if selectionLimit is not set', () => {
         const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
@@ -387,26 +630,25 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
-              selectionLimit: 1,
+              selectionLimit: null,
             },
           },
         };
 
         const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['two']);
+        expect(result.selectedValues).to.deep.equal(['one', 'two']);
       });
 
-      it('add the highlighted value to the selection if selectionLimit is not set', () => {
+      it('limits the selection to specified number of items', () => {
         const state: ListState<string> = {
-          highlightedValue: 'two',
-          selectedValues: ['one'],
+          highlightedValue: 'three',
+          selectedValues: ['one', 'two'],
         };
 
         const action: ListReducerAction<string, ListState<string>> = {
-          type: ListActionTypes.itemClick,
-          event: {
-            key: 'Enter',
-          } as any,
+          type: ListActionTypes.keyDown,
+          key: 'Enter',
+          event: {} as any,
           props: {
             current: {
               items: ['one', 'two', 'three'],
@@ -417,14 +659,13 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
-              selectionLimit: null,
+              selectionLimit: 2,
             },
           },
-          item: 'two',
         };
 
         const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['one', 'two']);
+        expect(result.selectedValues).to.deep.equal(['two', 'three']);
       });
     });
   });
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index a96423cf072c9b..a97ea3c0147ed5 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -30,7 +30,10 @@ function findValidItemToHighlight<ItemValue>(
   isItemDisabled: ItemPredicate<ItemValue>,
   wrapAround: boolean,
 ): number {
-  if (items.length === 0 || items.every((item, itemIndex) => isItemDisabled(item, itemIndex))) {
+  if (
+    items.length === 0 ||
+    (!includeDisabledItems && items.every((item, itemIndex) => isItemDisabled(item, itemIndex)))
+  ) {
     return -1;
   }
 
@@ -149,6 +152,15 @@ function moveHighlight<ItemValue>(
     wrapAround,
   );
 
+  // If there are no valid items to highlight, return the previously highlighted item (if it's still valid).
+  if (
+    nextIndex === -1 &&
+    previouslyHighlightedValue !== null &&
+    !isItemDisabled(previouslyHighlightedValue, previouslyHighlightedIndex)
+  ) {
+    return previouslyHighlightedValue;
+  }
+
   return items[nextIndex] ?? null;
 }
 
@@ -358,7 +370,6 @@ function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
     ? state.highlightedValue
     : moveHighlight(state.highlightedValue, 1, props);
 
-  // use `for` instead of `while` prevent infinite loop
   for (let index = 0; index < items.length; index += 1) {
     // Return un-mutated state if looped back to the currently highlighted value
     if (!nextItem || (!startWithCurrentItem && state.highlightedValue === nextItem)) {

From 091cd3a5af59328412532077f818be61c2a8e465 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 15:00:54 +0200
Subject: [PATCH 33/49] Do not focus a disabled first item after initially
 populating the options

---
 .../mui-base/src/useList/listReducer.test.ts  | 266 +++++++++++++++++-
 packages/mui-base/src/useList/listReducer.ts  |  19 +-
 2 files changed, 277 insertions(+), 8 deletions(-)

diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index 525f0920a37152..0ba33ffde00ce5 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -36,7 +36,7 @@ describe('listReducer', () => {
   });
 
   describe('action: blur', () => {
-    it('resets the highlightedIndex', () => {
+    it('resets the highlightedValue', () => {
       const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: [],
@@ -65,7 +65,7 @@ describe('listReducer', () => {
     });
   });
 
-  describe('action: optionClick', () => {
+  describe('action: itemClick', () => {
     it('sets the selectedValues to the clicked value', () => {
       const state: ListState<string> = {
         highlightedValue: 'a',
@@ -816,4 +816,266 @@ describe('listReducer', () => {
       expect(result.highlightedValue).to.equal('three');
     });
   });
+
+  describe('action: itemsChange', () => {
+    const irrelevantConfig = {
+      disableListWrap: false,
+      disabledItemsFocusable: false,
+      focusManagement: 'activeDescendant' as const,
+      isItemDisabled: () => false,
+      itemStringifier: (option: any) => option,
+      orientation: 'vertical' as const,
+      selectionLimit: null,
+    };
+
+    describe('using default item comparer', () => {
+      it('keeps the highlighted value if it is present among the new items', () => {
+        const state: ListState<string> = {
+          highlightedValue: '1',
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2'],
+          previousItems: ['0', '1', '2'],
+          props: {
+            current: {
+              items: ['1', '2'],
+              itemComparer: (o, v) => o === v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue).to.equal('1');
+      });
+
+      it('resets the highlighted value if it is not present among the new items', () => {
+        const state: ListState<string> = {
+          highlightedValue: '0',
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2'],
+          previousItems: ['0', '1', '2'],
+          props: {
+            current: {
+              items: ['1', '2'],
+              itemComparer: (o, v) => o === v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue).to.equal(null);
+      });
+
+      it('keeps the selected values if they are present among the new items', () => {
+        const state: ListState<string> = {
+          highlightedValue: '1',
+          selectedValues: ['1', '2'],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2'],
+          previousItems: ['0', '1', '2'],
+          props: {
+            current: {
+              items: ['1', '2'],
+              itemComparer: (o, v) => o === v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.selectedValues).to.deep.equal(['1', '2']);
+      });
+
+      it('removes the values from the selection if they are no longer present among the new items', () => {
+        const state: ListState<string> = {
+          highlightedValue: '1',
+          selectedValues: ['0', '2'],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2'],
+          previousItems: ['0', '1', '2'],
+          props: {
+            current: {
+              items: ['1', '2'],
+              itemComparer: (o, v) => o === v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.selectedValues).to.deep.equal(['2']);
+      });
+    });
+
+    describe('using custom item comparer', () => {
+      type ItemType = { v: string };
+      it('keeps the highlighted value if it is present among the new items', () => {
+        const state: ListState<ItemType> = {
+          highlightedValue: { v: '1' },
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: [{ v: '1' }, { v: '2' }],
+          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
+          props: {
+            current: {
+              items: [{ v: '1' }, { v: '2' }],
+              itemComparer: (a, b) => a.v === b.v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue?.v).to.equal('1');
+      });
+
+      it('resets the highlighted value if it is not present among the new items', () => {
+        const state: ListState<ItemType> = {
+          highlightedValue: { v: '0' },
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: [{ v: '1' }, { v: '2' }],
+          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
+          props: {
+            current: {
+              items: [{ v: '1' }, { v: '2' }],
+              itemComparer: (a, b) => a.v === b.v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue).to.equal(null);
+      });
+
+      it('keeps the selected values if they are present among the new items', () => {
+        const state: ListState<ItemType> = {
+          highlightedValue: { v: '1' },
+          selectedValues: [{ v: '1' }, { v: '2' }],
+        };
+
+        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: [{ v: '1' }, { v: '2' }],
+          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
+          props: {
+            current: {
+              items: [{ v: '1' }, { v: '2' }],
+              itemComparer: (a, b) => a.v === b.v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.selectedValues.map((sv) => sv.v)).to.deep.equal(['1', '2']);
+      });
+
+      it('removes the values from the selection if they are no longer present among the new items', () => {
+        const state: ListState<ItemType> = {
+          highlightedValue: { v: '1' },
+          selectedValues: [{ v: '0' }, { v: '2' }],
+        };
+
+        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: [{ v: '1' }, { v: '2' }],
+          previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
+          props: {
+            current: {
+              items: [{ v: '1' }, { v: '2' }],
+              itemComparer: (a, b) => a.v === b.v,
+              ...irrelevantConfig,
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.selectedValues.map((sv) => sv.v)).to.deep.equal(['2']);
+      });
+    });
+
+    describe('after the items are initialized', () => {
+      it('highlights the first item when using DOM focus management', () => {
+        const state: ListState<string> = {
+          highlightedValue: null,
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2'],
+          previousItems: [],
+          props: {
+            current: {
+              ...irrelevantConfig,
+              items: ['1', '2'],
+              itemComparer: (o, v) => o === v,
+              focusManagement: 'DOM',
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue).to.equal('1');
+      });
+
+      it('highlights the first enabled item when using DOM focus management', () => {
+        const state: ListState<string> = {
+          highlightedValue: null,
+          selectedValues: [],
+        };
+
+        const action: ListReducerAction<string, ListState<string>> = {
+          type: ListActionTypes.itemsChange,
+          event: null,
+          items: ['1', '2', '3'],
+          previousItems: [],
+          props: {
+            current: {
+              ...irrelevantConfig,
+              items: ['1', '2', '3'],
+              itemComparer: (o, v) => o === v,
+              focusManagement: 'DOM',
+              isItemDisabled: (item) => ['1', '2'].includes(item),
+            },
+          },
+        };
+
+        const result = listReducer(state, action);
+        expect(result.highlightedValue).to.equal('3');
+      });
+    });
+  });
 });
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index a97ea3c0147ed5..89e81cb49596b2 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -20,7 +20,7 @@ const pageSize = 5;
  * @param includeDisabledItems Whether to include disabled items in the search.
  * @param isItemDisabled A function that determines whether an item is disabled.
  * @param wrapAround Whether to wrap around the list when searching.
- * @returns
+ * @returns The index of the next valid item to highlight or -1 if no valid item is found.
  */
 function findValidItemToHighlight<ItemValue>(
   currentIndex: number,
@@ -78,11 +78,19 @@ function moveHighlight<ItemValue>(
   offset: number | 'reset' | 'start' | 'end',
   listConfig: ListActionAddOnValue<ItemValue>,
 ) {
-  const { items, isItemDisabled, disableListWrap, disabledItemsFocusable, itemComparer } =
-    listConfig;
+  const {
+    items,
+    isItemDisabled,
+    disableListWrap,
+    disabledItemsFocusable,
+    itemComparer,
+    focusManagement,
+  } = listConfig;
 
   // TODO: make this configurable
-  const defaultHighlightedIndex = -1;
+  // The always should be an item highlighted when focus is managed by the DOM
+  // so that it's accessible by the `tab` key.
+  const defaultHighlightedIndex = focusManagement === 'DOM' ? 0 : -1;
   const maxIndex = items.length - 1;
 
   const previouslyHighlightedIndex =
@@ -407,8 +415,7 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
   if (state.highlightedValue != null) {
     newHighlightedValue = items.find((item) => itemComparer(item, state.highlightedValue!)) ?? null;
   } else if (focusManagement === 'DOM' && previousItems.length === 0) {
-    // TODO: exclude disabled items
-    newHighlightedValue = items[0] ?? null;
+    newHighlightedValue = moveHighlight(null, 'reset', props);
   }
 
   // exclude selected values that are no longer in the items list

From d46eb122a52e943ab766c29c715a71cd1f971e1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 15:28:19 +0200
Subject: [PATCH 34/49] Configurable pageSize in useList

---
 .../mui-base/src/useList/listReducer.test.ts  | 158 ++++++++++++++----
 packages/mui-base/src/useList/listReducer.ts  |   5 +-
 packages/mui-base/src/useList/useList.ts      |   2 +
 .../mui-base/src/useList/useList.types.ts     |   7 +
 4 files changed, 134 insertions(+), 38 deletions(-)

diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index 0ba33ffde00ce5..0393e166785a55 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -26,6 +26,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -55,6 +56,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -85,6 +87,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -114,6 +117,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: 1,
           },
         },
@@ -143,6 +147,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -173,6 +178,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: 2,
           },
         },
@@ -201,6 +207,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -214,7 +221,7 @@ describe('listReducer', () => {
 
   describe('action: keyDown', () => {
     interface KeydownTestCase {
-      name: string;
+      description: string;
       key: string;
       initialHighlightedItem: string | null;
       disabledItemFocusable: boolean;
@@ -225,7 +232,7 @@ describe('listReducer', () => {
 
     const testCases: KeydownTestCase[] = [
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -234,7 +241,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'highlights the first enabled item',
+        description: 'highlights the first enabled item',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -243,7 +250,7 @@ describe('listReducer', () => {
         expected: '2',
       },
       {
-        name: 'highlights the first enabled item',
+        description: 'highlights the first enabled item',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -252,7 +259,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'highlights the first item even if it is disabled',
+        description: 'highlights the first item even if it is disabled',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -261,7 +268,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'all disabled',
+        description: 'all disabled',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -270,7 +277,7 @@ describe('listReducer', () => {
         expected: null,
       },
       {
-        name: 'all disabled but focusable',
+        description: 'all disabled but focusable',
         key: 'Home',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -279,7 +286,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -288,7 +295,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'highlights the last enabled item',
+        description: 'highlights the last enabled item',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -297,7 +304,7 @@ describe('listReducer', () => {
         expected: '4',
       },
       {
-        name: 'highlights the last enabled item',
+        description: 'highlights the last enabled item',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -306,7 +313,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'highlights the last item even if it is disabled',
+        description: 'highlights the last item even if it is disabled',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -315,7 +322,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'all disabled',
+        description: 'all disabled',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -324,7 +331,7 @@ describe('listReducer', () => {
         expected: null,
       },
       {
-        name: 'all disabled but focusable',
+        description: 'all disabled but focusable',
         key: 'End',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -333,7 +340,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'ArrowDown',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -342,7 +349,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'ArrowDown',
         initialHighlightedItem: '1',
         disabledItemFocusable: false,
@@ -351,7 +358,7 @@ describe('listReducer', () => {
         expected: '2',
       },
       {
-        name: 'skips the disabled item',
+        description: 'skips the disabled item',
         key: 'ArrowDown',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -360,7 +367,7 @@ describe('listReducer', () => {
         expected: '2',
       },
       {
-        name: 'skips multiple disabled items',
+        description: 'skips multiple disabled items',
         key: 'ArrowDown',
         initialHighlightedItem: '1',
         disabledItemFocusable: false,
@@ -369,7 +376,7 @@ describe('listReducer', () => {
         expected: '4',
       },
       {
-        name: 'skips the disabled items and wraps around',
+        description: 'skips the disabled items and wraps around',
         key: 'ArrowDown',
         initialHighlightedItem: '3',
         disabledItemFocusable: false,
@@ -378,7 +385,7 @@ describe('listReducer', () => {
         expected: '2',
       },
       {
-        name: 'focuses the disabled item',
+        description: 'focuses the disabled item',
         key: 'ArrowDown',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -387,7 +394,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'does not wrap around',
+        description: 'does not wrap around',
         key: 'ArrowDown',
         initialHighlightedItem: '5',
         disabledItemFocusable: false,
@@ -396,7 +403,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'remains on the same item when all the next are disabled',
+        description: 'remains on the same item when all the next are disabled',
         key: 'ArrowDown',
         initialHighlightedItem: '3',
         disabledItemFocusable: false,
@@ -405,7 +412,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'all disabled',
+        description: 'all disabled',
         key: 'ArrowDown',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -414,7 +421,7 @@ describe('listReducer', () => {
         expected: null,
       },
       {
-        name: 'all disabled but focusable',
+        description: 'all disabled but focusable',
         key: 'ArrowDown',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -423,7 +430,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'ArrowUp',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -432,7 +439,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'happy path',
+        description: 'happy path',
         key: 'ArrowUp',
         initialHighlightedItem: '2',
         disabledItemFocusable: false,
@@ -441,7 +448,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'skips the disabled item',
+        description: 'skips the disabled item',
         key: 'ArrowUp',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -450,7 +457,7 @@ describe('listReducer', () => {
         expected: '4',
       },
       {
-        name: 'skips multiple disabled items',
+        description: 'skips multiple disabled items',
         key: 'ArrowUp',
         initialHighlightedItem: '1',
         disabledItemFocusable: false,
@@ -459,7 +466,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'skips the disabled items and wraps around',
+        description: 'skips the disabled items and wraps around',
         key: 'ArrowUp',
         initialHighlightedItem: '2',
         disabledItemFocusable: false,
@@ -468,7 +475,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'focuses the disabled item',
+        description: 'focuses the disabled item',
         key: 'ArrowUp',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -477,7 +484,7 @@ describe('listReducer', () => {
         expected: '5',
       },
       {
-        name: 'does not wrap around',
+        description: 'does not wrap around',
         key: 'ArrowUp',
         initialHighlightedItem: '1',
         disabledItemFocusable: false,
@@ -486,7 +493,7 @@ describe('listReducer', () => {
         expected: '1',
       },
       {
-        name: 'remains on the same item when all the previous are disabled',
+        description: 'remains on the same item when all the previous are disabled',
         key: 'ArrowUp',
         initialHighlightedItem: '3',
         disabledItemFocusable: false,
@@ -495,7 +502,7 @@ describe('listReducer', () => {
         expected: '3',
       },
       {
-        name: 'all disabled',
+        description: 'all disabled',
         key: 'ArrowUp',
         initialHighlightedItem: null,
         disabledItemFocusable: false,
@@ -504,7 +511,7 @@ describe('listReducer', () => {
         expected: null,
       },
       {
-        name: 'all disabled but focusable',
+        description: 'all disabled but focusable',
         key: 'ArrowUp',
         initialHighlightedItem: null,
         disabledItemFocusable: true,
@@ -512,6 +519,78 @@ describe('listReducer', () => {
         disableListWrap: false,
         expected: '5',
       },
+      {
+        description: 'happy path',
+        key: 'PageDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '3',
+      },
+      {
+        description: 'skips the disabled item',
+        key: 'PageDown',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: ['3'],
+        disableListWrap: false,
+        expected: '4',
+      },
+      {
+        description: 'does not wrap around, no matter the setting',
+        key: 'PageDown',
+        initialHighlightedItem: '4',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '5',
+      },
+      {
+        description: 'does not wrap around, no matter the setting, and skips the disabled item',
+        key: 'PageDown',
+        initialHighlightedItem: '3',
+        disabledItemFocusable: false,
+        disabledItems: ['5'],
+        disableListWrap: false,
+        expected: '4',
+      },
+      {
+        description: 'happy path',
+        key: 'PageUp',
+        initialHighlightedItem: null,
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        description: 'skips the disabled item',
+        key: 'PageUp',
+        initialHighlightedItem: '5',
+        disabledItemFocusable: false,
+        disabledItems: ['2'],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        description: 'does not wrap around, no matter the setting',
+        key: 'PageUp',
+        initialHighlightedItem: '2',
+        disabledItemFocusable: false,
+        disabledItems: [],
+        disableListWrap: false,
+        expected: '1',
+      },
+      {
+        description: 'does not wrap around, no matter the setting, and skips the disabled item',
+        key: 'PageUp',
+        initialHighlightedItem: '3',
+        disabledItemFocusable: false,
+        disabledItems: ['1'],
+        disableListWrap: false,
+        expected: '2',
+      },
     ];
 
     testCases.forEach((spec: KeydownTestCase) => {
@@ -520,7 +599,7 @@ describe('listReducer', () => {
       }', disabledItemsFocusable: ${spec.disabledItemFocusable}, disableListWrap: ${
         spec.disableListWrap
       }, disabledItems: [${spec.disabledItems.join()}]`, () => {
-        it(`${spec.name}: should highlight the '${spec.expected}' item after the ${spec.key} is pressed`, () => {
+        it(`${spec.description}: should highlight the '${spec.expected}' item after the ${spec.key} is pressed`, () => {
           const state: ListState<string> = {
             highlightedValue: spec.initialHighlightedItem,
             selectedValues: [],
@@ -540,6 +619,7 @@ describe('listReducer', () => {
                 itemComparer: (o, v) => o === v,
                 itemStringifier: (option) => option,
                 orientation: 'vertical',
+                pageSize: 3,
                 selectionLimit: null,
               },
             },
@@ -572,6 +652,7 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
+              pageSize: 5,
               selectionLimit: null,
             },
           },
@@ -601,6 +682,7 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
+              pageSize: 5,
               selectionLimit: 1,
             },
           },
@@ -630,6 +712,7 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
+              pageSize: 5,
               selectionLimit: null,
             },
           },
@@ -659,6 +742,7 @@ describe('listReducer', () => {
               itemComparer: (o, v) => o === v,
               itemStringifier: (option) => option,
               orientation: 'vertical',
+              pageSize: 5,
               selectionLimit: 2,
             },
           },
@@ -691,6 +775,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -720,6 +805,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -749,6 +835,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -778,6 +865,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -807,6 +895,7 @@ describe('listReducer', () => {
             itemComparer: (o, v) => o === v,
             itemStringifier: (option) => option,
             orientation: 'vertical',
+            pageSize: 5,
             selectionLimit: null,
           },
         },
@@ -825,6 +914,7 @@ describe('listReducer', () => {
       isItemDisabled: () => false,
       itemStringifier: (option: any) => option,
       orientation: 'vertical' as const,
+      pageSize: 5,
       selectionLimit: null,
     };
 
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index 89e81cb49596b2..fbddf4ecf82569 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -8,9 +8,6 @@ import {
 
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
-// TODO: make page size configurable
-const pageSize = 5;
-
 /**
  * Looks up the next valid item to highlight within the list.
  *
@@ -248,7 +245,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
   parameters: ListActionAddOnValue<ItemValue>,
 ): State {
   const previouslySelectedValue = state.highlightedValue;
-  const { orientation } = parameters;
+  const { orientation, pageSize } = parameters;
 
   switch (key) {
     case 'Home':
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 33c2e354238e29..92ef69fba3f461 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -69,6 +69,7 @@ function useList<
     onChange,
     onHighlightChange,
     orientation = 'vertical',
+    pageSize = 5,
     selectionLimit = null,
     stateReducer: externalReducer,
   } = params;
@@ -158,6 +159,7 @@ function useList<
       itemStringifier,
       onHighlightChange: handleHighlightChange,
       orientation,
+      pageSize,
       selectionLimit,
       stateComparers,
     },
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index a89fef3273cc3c..372c156f3fe616 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -15,6 +15,7 @@ type ListActionAddOnValueRequiredKeys =
   | 'items'
   | 'itemStringifier'
   | 'orientation'
+  | 'pageSize'
   | 'selectionLimit';
 
 /**
@@ -134,6 +135,12 @@ export interface UseListParameters<
    * `onChange` and `onHighlightChange` callbacks are also fired.
    */
   onStateChange?: StateChangeCallback<State>;
+  /**
+   * The number of items skip when using the page up and page down keys.
+   *
+   * @default 5
+   */
+  pageSize?: number;
   /**
    * A function that tests equality between two items' values.
    * @default (a, b) => a === b

From 3c7faf48b99cd5e94f89bdb391d6955f4274d295 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 16:16:17 +0200
Subject: [PATCH 35/49] Small changes

---
 .../mui-base/src/useList/useListItem.types.ts |  1 +
 packages/mui-base/src/useSelect/useSelect.ts  | 33 +++++++------------
 2 files changed, 12 insertions(+), 22 deletions(-)

diff --git a/packages/mui-base/src/useList/useListItem.types.ts b/packages/mui-base/src/useList/useListItem.types.ts
index ffd150333b4725..cd40d73bc4b3b6 100644
--- a/packages/mui-base/src/useList/useListItem.types.ts
+++ b/packages/mui-base/src/useList/useListItem.types.ts
@@ -4,6 +4,7 @@ export interface UseListItemParameters<ItemValue> {
   /**
    * If `true`, the list item will dispatch the `itemHover` action on pointer over.
    * Since the use cases for it are rare, it's disabled by default.
+   * It could be used to mimic the native `select` behavior, which highlights the hovered item.
    *
    * @default false
    */
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 33c35efe660a6a..c06a9ffa92a4f3 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -270,7 +270,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     [value, openProp],
   );
 
-  const useListboxParameters: UseListParameters<
+  const useListParameters: UseListParameters<
     OptionValue,
     SelectInternalState<OptionValue>,
     SelectAction
@@ -314,10 +314,8 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     highlightedOption,
     selectedOptions,
     contextValue: listContextValue,
-    state,
-  } = useList(useListboxParameters);
-
-  const { open } = state;
+    state: { open },
+  } = useList(useListParameters);
 
   React.useEffect(() => {
     focusListboxIfRequested();
@@ -453,20 +451,14 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     [listContextValue, compoundComponentContextValue],
   );
 
+  let selectValue: SelectValue<OptionValue, Multiple>;
   if (props.multiple) {
-    return {
-      buttonActive,
-      buttonFocusVisible,
-      disabled,
-      getButtonProps,
-      getListboxProps,
-      getOptionMetadata,
-      contextValue,
-      open,
-      options: optionValues,
-      value: selectedOptions as SelectValue<OptionValue, Multiple>,
-      highlightedOption,
-    };
+    selectValue = selectedOptions as SelectValue<OptionValue, Multiple>;
+  } else {
+    selectValue = (selectedOptions.length > 0 ? selectedOptions[0] : null) as SelectValue<
+      OptionValue,
+      Multiple
+    >;
   }
 
   return {
@@ -479,10 +471,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     contextValue,
     open,
     options: optionValues,
-    value: (selectedOptions.length > 0 ? selectedOptions[0] : null) as SelectValue<
-      OptionValue,
-      Multiple
-    >,
+    value: selectValue,
     highlightedOption,
   };
 }

From 843e8820b01231d47dfd6ec9f11007220b029fab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 17:39:45 +0200
Subject: [PATCH 36/49] Highlight selected item in Select

---
 .../SelectUnstyled/SelectUnstyled.test.tsx    |  1 -
 packages/mui-base/src/useList/index.ts        |  1 +
 packages/mui-base/src/useList/listReducer.ts  |  8 ++--
 .../mui-base/src/useSelect/useSelect.test.tsx |  2 +
 packages/mui-base/src/useSelect/useSelect.ts  | 42 ++++++++-----------
 5 files changed, 24 insertions(+), 30 deletions(-)
 create mode 100644 packages/mui-base/src/useSelect/useSelect.test.tsx

diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index 08d79c413208e8..fdb929d440c98f 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -140,7 +140,6 @@ describe('<SelectUnstyled />', () => {
 
           const listbox = getByRole('listbox');
 
-          userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '1'
           userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '2'
           fireEvent.keyDown(listbox, { key });
 
diff --git a/packages/mui-base/src/useList/index.ts b/packages/mui-base/src/useList/index.ts
index 0ec25716f35ac3..78dd449f74e7c3 100644
--- a/packages/mui-base/src/useList/index.ts
+++ b/packages/mui-base/src/useList/index.ts
@@ -5,6 +5,7 @@ export { default as useListItem } from './useListItem';
 export * from './useListItem.types';
 
 export { default as listReducer } from './listReducer';
+export * from './listReducer';
 
 export * from './listActions.types';
 
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index fbddf4ecf82569..fbc2fed83666be 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -59,18 +59,16 @@ function findValidItemToHighlight<ItemValue>(
   }
 }
 
-// TODO: expose these functions for use in custom reducers
-
 /**
  * Gets the next item to highlight based on the current highlighted item and the search direction.
  *
  * @param previouslyHighlightedValue The item from which to start the search for the next candidate.
  * @param offset The offset from the previously highlighted item to search for the next candidate or a special named value ('reset', 'start', 'end').
- * @param props
+ * @param listConfig The confguration of the list.
  *
  * @returns The next item to highlight or null if no item is valid.
  */
-function moveHighlight<ItemValue>(
+export function moveHighlight<ItemValue>(
   previouslyHighlightedValue: ItemValue | null,
   offset: number | 'reset' | 'start' | 'end',
   listConfig: ListActionAddOnValue<ItemValue>,
@@ -179,7 +177,7 @@ function moveHighlight<ItemValue>(
  *
  * @returns The new array of selected items.
  */
-function toggleSelection<ItemValue>(
+export function toggleSelection<ItemValue>(
   item: ItemValue,
   selectedValues: ItemValue[],
   selectionLimit: number | null,
diff --git a/packages/mui-base/src/useSelect/useSelect.test.tsx b/packages/mui-base/src/useSelect/useSelect.test.tsx
new file mode 100644
index 00000000000000..36cb26f7c86683
--- /dev/null
+++ b/packages/mui-base/src/useSelect/useSelect.test.tsx
@@ -0,0 +1,2 @@
+// TODO: test it properly
+describe('useSelect', () => {});
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index c06a9ffa92a4f3..456a0ad9f7025c 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -22,6 +22,7 @@ import useList, {
   UseListParameters,
   ListAction,
   ListActionAddOn,
+  moveHighlight,
 } from '../useList';
 import { EventHandlers } from '../utils/types';
 import defaultOptionStringifier from './defaultOptionStringifier';
@@ -134,25 +135,40 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
       const { open } = state;
 
       switch (action.type) {
-        case SelectActionTypes.buttonClick:
+        case SelectActionTypes.buttonClick: {
+          const itemToHighlight =
+            state.selectedValues[0] ??
+            moveHighlight<OptionValue>(null, 'start', action.props.current!);
+
           return {
             ...state,
             open: !open,
+            highlightedValue: !open ? itemToHighlight : null,
           };
+        }
 
         case SelectActionTypes.buttonArrowKeyDown:
           if (action.event.key === 'ArrowDown') {
+            const itemToHighlight =
+              state.selectedValues[0] ??
+              moveHighlight<OptionValue>(null, 'start', action.props.current!);
+
             return {
               ...state,
               open: true,
+              highlightedValue: itemToHighlight,
             };
           }
 
           if (action.event.key === 'ArrowUp') {
+            const itemToHighlight =
+              state.selectedValues[0] ??
+              moveHighlight<OptionValue>(null, 'end', action.props.current!);
+
             return {
               ...state,
               open: true,
-              // TODO: highlight last item
+              highlightedValue: itemToHighlight,
             };
           }
 
@@ -170,18 +186,6 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
 
       switch (action.type) {
         case ListActionTypes.keyDown:
-          // change selection when listbox is closed
-          if (
-            (action.event.key === 'ArrowUp' || action.event.key === 'ArrowDown') &&
-            !open &&
-            !multiple
-          ) {
-            return {
-              ...newState,
-              selectedValues: newState.highlightedValue != null ? [newState.highlightedValue] : [],
-            };
-          }
-
           if (
             !multiple &&
             (action.event.key === 'Enter' ||
@@ -206,19 +210,9 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
 
           break;
 
-        case ListActionTypes.setState:
-        case ListActionTypes.itemsChange:
-          return {
-            ...newState,
-            highlightedValue:
-              newState.selectedValues.length > 0 ? newState.selectedValues[0] : null,
-          };
-
         case ListActionTypes.blur:
           return {
             ...newState,
-            highlightedValue:
-              newState.selectedValues.length > 0 ? newState.selectedValues[0] : null,
             open: false,
           };
 

From 85878a2a5e295ca0ed98ddedbf787a600f5ece05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 00:22:22 +0200
Subject: [PATCH 37/49] Extract reducers and add a few tests

---
 packages/mui-base/src/useList/useList.ts      |  12 +-
 .../mui-base/src/useList/useList.types.ts     |  22 ++-
 packages/mui-base/src/useMenu/menuReducer.ts  |  43 ++++
 packages/mui-base/src/useMenu/useMenu.ts      |  49 +----
 .../src/useSelect/selectReducer.test.ts       | 185 ++++++++++++++++++
 .../mui-base/src/useSelect/selectReducer.ts   | 101 ++++++++++
 .../mui-base/src/useSelect/useSelect.test.tsx |  25 ++-
 packages/mui-base/src/useSelect/useSelect.ts  | 117 +----------
 .../mui-base/src/useSelect/useSelect.types.ts |   1 +
 .../src/useTabsList/tabsListReducer.ts        |  34 ++++
 .../mui-base/src/useTabsList/useTabsList.ts   |  45 +----
 11 files changed, 426 insertions(+), 208 deletions(-)
 create mode 100644 packages/mui-base/src/useMenu/menuReducer.ts
 create mode 100644 packages/mui-base/src/useSelect/selectReducer.test.ts
 create mode 100644 packages/mui-base/src/useSelect/selectReducer.ts
 create mode 100644 packages/mui-base/src/useTabsList/tabsListReducer.ts

diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 92ef69fba3f461..efcddfb217bfc2 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -51,7 +51,8 @@ function useList<
   ItemValue,
   State extends ListState<ItemValue> = ListState<ItemValue>,
   CustomAction extends ControllableReducerAction = never,
->(params: UseListParameters<ItemValue, State, CustomAction>) {
+  CustomActionAddon = {},
+>(params: UseListParameters<ItemValue, State, CustomAction, CustomActionAddon>) {
   const {
     controlledProps = EMPTY_OBJECT,
     disabledItemsFocusable = false,
@@ -70,6 +71,7 @@ function useList<
     onHighlightChange,
     orientation = 'vertical',
     pageSize = 5,
+    reducerActionAddon: externalActionAddon = {} as CustomActionAddon,
     selectionLimit = null,
     stateReducer: externalReducer,
   } = params;
@@ -169,9 +171,9 @@ function useList<
   const initialState = getInitialState();
   const reducer = externalReducer ?? defaultReducer;
 
-  const actionAddOn: ListActionAddOn<ItemValue> = React.useMemo(
-    () => ({ props: propsWithDefaults }),
-    [propsWithDefaults],
+  const actionAddOn: ListActionAddOn<ItemValue> & CustomActionAddon = React.useMemo(
+    () => ({ ...externalActionAddon, props: propsWithDefaults }),
+    [propsWithDefaults, externalActionAddon],
   );
 
   type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue, State>;
@@ -179,7 +181,7 @@ function useList<
   const [state, dispatch] = useControllableReducer<
     State,
     ListActionsWithCustomActions,
-    ListActionAddOn<ItemValue>
+    ListActionAddOn<ItemValue> & CustomActionAddon
   >({
     reducer: reducer as any,
     actionAddOn,
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 372c156f3fe616..1e20b1ac187464 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -29,11 +29,11 @@ export type ListActionAddOn<ItemValue> = {
   props: React.RefObject<ListActionAddOnValue<ItemValue>>;
 };
 
-export type ListReducerAction<ItemValue, State extends ListState<ItemValue>> = ListAction<
+export type ListReducerAction<
   ItemValue,
-  State
-> &
-  ListActionAddOn<ItemValue>;
+  State extends ListState<ItemValue>,
+  CustomActionAddon = {},
+> = ListAction<ItemValue, State> & ListActionAddOn<ItemValue> & CustomActionAddon;
 
 export interface ListState<ItemValue> {
   /**
@@ -46,9 +46,9 @@ export interface ListState<ItemValue> {
   selectedValues: ItemValue[];
 }
 
-export type ListReducer<ItemValue, State extends ListState<ItemValue>> = (
+export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomActionAddon> = (
   state: State,
-  action: ListReducerAction<ItemValue, State>,
+  action: ListReducerAction<ItemValue, State, CustomActionAddon>,
 ) => State;
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
@@ -57,6 +57,7 @@ export interface UseListParameters<
   ItemValue,
   State extends ListState<ItemValue> = ListState<ItemValue>,
   CustomAction extends ControllableReducerAction = never,
+  CustomActionAddon = {},
 > {
   /**
    * The externally controlled values (highlighted and selected item(s)) of the list.
@@ -155,11 +156,14 @@ export interface UseListParameters<
    * Array of list items.
    */
   items: ItemValue[];
+  /**
+   * Additional data to be passed to all the reducer actions.
+   */
+  reducerActionAddon?: CustomActionAddon;
   /**
    * Orientation of the items in the list.
    * Determines the actions that are performed when arrow keys are pressed.
    */
-  // TODO: add vertical-reverse
   orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
   /**
    * Maximum number of items that can be selected at once.
@@ -174,7 +178,9 @@ export interface UseListParameters<
    */
   stateReducer?: (
     state: State,
-    action: (ListAction<ItemValue, State> | CustomAction) & ListActionAddOn<ItemValue>,
+    action: (ListAction<ItemValue, State> | CustomAction) &
+      ListActionAddOn<ItemValue> &
+      CustomActionAddon,
   ) => State;
 }
 
diff --git a/packages/mui-base/src/useMenu/menuReducer.ts b/packages/mui-base/src/useMenu/menuReducer.ts
new file mode 100644
index 00000000000000..cd4e639fd3f8c3
--- /dev/null
+++ b/packages/mui-base/src/useMenu/menuReducer.ts
@@ -0,0 +1,43 @@
+import { ListAction, ListActionAddOn, ListActionTypes, listReducer } from '../useList';
+import { MenuInternalState } from './useMenu.types';
+
+export default function menuReducer(
+  state: MenuInternalState,
+  action: ListAction<string, MenuInternalState> &
+    ListActionAddOn<string> & { listboxRef: React.RefObject<HTMLElement> },
+) {
+  if (action.type === ListActionTypes.itemHover || action.type === ListActionTypes.setState) {
+    return state;
+  }
+
+  const newState = listReducer(state, action);
+
+  // make sure an item is always highlighted
+  if (newState.highlightedValue === null && action.props.current!.items.length > 0) {
+    return {
+      ...newState,
+      highlightedValue: action.props.current!.items[0],
+    };
+  }
+
+  if (action.type === ListActionTypes.keyDown) {
+    if (action.event.key === 'Escape') {
+      return {
+        ...newState,
+        open: false,
+      };
+    }
+  }
+
+  if (action.type === ListActionTypes.blur) {
+    if (!action.listboxRef.current?.contains(action.event.relatedTarget)) {
+      return {
+        ...newState,
+        open: false,
+        highlightedValue: action.props.current!.items[0],
+      };
+    }
+  }
+
+  return newState;
+}
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index a9e342324dcbe3..7f8e22689f9a22 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
-import useList, { listReducer, ListActionTypes, ListActionAddOn, ListAction } from '../useList';
+import useList from '../useList';
 import {
   MenuInternalState,
   UseMenuListboxSlotProps,
@@ -11,6 +11,7 @@ import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { MenuItemMetadata } from '../useMenuItem';
 import { StateChangeCallback } from '../utils/useControllableReducer.types';
+import menuReducer from './menuReducer';
 
 /**
  *
@@ -46,49 +47,6 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     [subitems],
   );
 
-  const menuReducer = React.useCallback(
-    (
-      state: MenuInternalState,
-      action: ListAction<string, MenuInternalState> & ListActionAddOn<string>,
-    ): MenuInternalState => {
-      if (action.type === ListActionTypes.itemHover || action.type === ListActionTypes.setState) {
-        return state;
-      }
-
-      const newState = listReducer(state, action);
-
-      // make sure an item is always highlighted
-      if (newState.highlightedValue === null && action.props.current!.items.length > 0) {
-        return {
-          ...newState,
-          highlightedValue: action.props.current!.items[0],
-        };
-      }
-
-      if (action.type === ListActionTypes.keyDown) {
-        if (action.event.key === 'Escape') {
-          return {
-            ...newState,
-            open: false,
-          };
-        }
-      }
-
-      if (action.type === ListActionTypes.blur) {
-        if (!listboxRef.current?.contains(action.event.relatedTarget)) {
-          return {
-            ...newState,
-            open: false,
-            highlightedValue: action.props.current!.items[0],
-          };
-        }
-      }
-
-      return newState;
-    },
-    [],
-  );
-
   const controlledProps = React.useMemo(() => ({ open: openProp }), [openProp]);
 
   const stateChangeHandler: StateChangeCallback<MenuInternalState> = React.useCallback(
@@ -110,7 +68,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     highlightedOption,
     contextValue: listContextValue,
     state: { open },
-  } = useList<string, MenuInternalState>({
+  } = useList({
     controlledProps,
     disabledItemsFocusable: true,
     focusManagement: 'DOM',
@@ -126,6 +84,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
       subitems.get(id)?.label || subitems.get(id)?.ref.current?.innerText,
     listRef: handleRef,
     onStateChange: stateChangeHandler,
+    reducerActionAddon: { listboxRef },
     selectionLimit: 0,
     stateReducer: menuReducer,
   });
diff --git a/packages/mui-base/src/useSelect/selectReducer.test.ts b/packages/mui-base/src/useSelect/selectReducer.test.ts
new file mode 100644
index 00000000000000..c1b6fd8acde58f
--- /dev/null
+++ b/packages/mui-base/src/useSelect/selectReducer.test.ts
@@ -0,0 +1,185 @@
+import { expect } from 'chai';
+import selectReducer from './selectReducer';
+import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
+import { ListActionAddOn } from '../useList';
+
+describe('selectReducer', () => {
+  const irrelevantConfig = {
+    items: [],
+    disableListWrap: false,
+    disabledItemsFocusable: false,
+    focusManagement: 'activeDescendant' as const,
+    isItemDisabled: () => false,
+    itemComparer: (a: any, b: any) => a === b,
+    itemStringifier: (option: any) => option,
+    orientation: 'vertical' as const,
+    pageSize: 5,
+    selectionLimit: null,
+  };
+
+  describe('action: buttonClick', () => {
+    it('opens the select if it was closed', () => {
+      const state: SelectInternalState<unknown> = {
+        highlightedValue: null,
+        selectedValues: [],
+        open: false,
+      };
+
+      const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+        type: SelectActionTypes.buttonClick,
+        event: {} as any, // not relevant
+        props: {
+          current: irrelevantConfig,
+        },
+        multiple: false,
+      };
+
+      const result = selectReducer(state, action);
+      expect(result.open).to.equal(true);
+    });
+
+    it('closes the select if it was open', () => {
+      const state: SelectInternalState<unknown> = {
+        highlightedValue: null,
+        selectedValues: [],
+        open: true,
+      };
+
+      const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+        type: SelectActionTypes.buttonClick,
+        event: {} as any, // not relevant
+        props: {
+          current: irrelevantConfig,
+        },
+        multiple: false,
+      };
+
+      const result = selectReducer(state, action);
+      expect(result.open).to.equal(false);
+    });
+
+    it('highlights the first selected value if the select was closed', () => {
+      const state: SelectInternalState<string> = {
+        highlightedValue: null,
+        selectedValues: ['2'],
+        open: false,
+      };
+
+      const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+        type: SelectActionTypes.buttonClick,
+        event: {} as any, // not relevant
+        props: {
+          current: {
+            ...irrelevantConfig,
+            items: ['1', '2', '3'],
+          },
+        },
+        multiple: false,
+      };
+
+      const result = selectReducer(state, action);
+      expect(result.highlightedValue).to.equal('2');
+    });
+
+    it('highlights the first value if the select was closed and nothing was selected', () => {
+      const state: SelectInternalState<string> = {
+        highlightedValue: null,
+        selectedValues: [],
+        open: false,
+      };
+
+      const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+        type: SelectActionTypes.buttonClick,
+        event: {} as any, // not relevant
+        props: {
+          current: {
+            ...irrelevantConfig,
+            items: ['1', '2', '3'],
+          },
+        },
+        multiple: false,
+      };
+
+      const result = selectReducer(state, action);
+      expect(result.highlightedValue).to.equal('1');
+    });
+  });
+
+  describe('action: buttonArrowKeyDown', () => {
+    [
+      { key: 'ArrowDown', expectedHighlight: '1' },
+      { key: 'ArrowUp', expectedHighlight: '3' },
+    ].forEach((testCase) => {
+      describe(`after ${testCase.key} was pressed`, () => {
+        it('opens the select if it was closed', () => {
+          const state: SelectInternalState<unknown> = {
+            highlightedValue: null,
+            selectedValues: [],
+            open: false,
+          };
+
+          const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+            type: SelectActionTypes.buttonArrowKeyDown,
+            key: testCase.key,
+            event: {} as any, // not relevant
+            props: {
+              current: irrelevantConfig,
+            },
+            multiple: false,
+          };
+
+          const result = selectReducer(state, action);
+          expect(result.open).to.equal(true);
+        });
+
+        it('highlights the first selected value if the select was closed', () => {
+          const state: SelectInternalState<string> = {
+            highlightedValue: null,
+            selectedValues: ['2'],
+            open: false,
+          };
+
+          const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+            type: SelectActionTypes.buttonArrowKeyDown,
+            key: testCase.key,
+            event: {} as any, // not relevant
+            props: {
+              current: {
+                ...irrelevantConfig,
+                items: ['1', '2', '3'],
+              },
+            },
+            multiple: false,
+          };
+
+          const result = selectReducer(state, action);
+          expect(result.highlightedValue).to.equal('2');
+        });
+
+        it(`highlights the ${testCase.expectedHighlight} value if the select was closed and nothing was selected`, () => {
+          const state: SelectInternalState<string> = {
+            highlightedValue: null,
+            selectedValues: [],
+            open: false,
+          };
+
+          const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+            type: SelectActionTypes.buttonArrowKeyDown,
+            key: testCase.key,
+            event: {} as any, // not relevant
+            props: {
+              current: {
+                ...irrelevantConfig,
+                items: ['1', '2', '3'],
+              },
+            },
+            multiple: false,
+          };
+
+          const result = selectReducer(state, action);
+          expect(result.highlightedValue).to.equal(testCase.expectedHighlight);
+        });
+      });
+    });
+  });
+});
diff --git a/packages/mui-base/src/useSelect/selectReducer.ts b/packages/mui-base/src/useSelect/selectReducer.ts
new file mode 100644
index 00000000000000..991a1bcf0635fb
--- /dev/null
+++ b/packages/mui-base/src/useSelect/selectReducer.ts
@@ -0,0 +1,101 @@
+import {
+  ListAction,
+  ListActionAddOn,
+  moveHighlight,
+  listReducer,
+  ListActionTypes,
+} from '../useList';
+import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
+
+export default function selectReducer<OptionValue>(
+  state: SelectInternalState<OptionValue>,
+  action: (ListAction<OptionValue, SelectInternalState<OptionValue>> | SelectAction) &
+    ListActionAddOn<OptionValue> & { multiple: boolean },
+) {
+  const { open } = state;
+  const { multiple: actionMultiple } = action;
+
+  switch (action.type) {
+    case SelectActionTypes.buttonClick: {
+      const itemToHighlight =
+        state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'start', action.props.current!);
+
+      return {
+        ...state,
+        open: !open,
+        highlightedValue: !open ? itemToHighlight : null,
+      };
+    }
+
+    case SelectActionTypes.buttonArrowKeyDown:
+      if (action.key === 'ArrowDown') {
+        const itemToHighlight =
+          state.selectedValues[0] ??
+          moveHighlight<OptionValue>(null, 'start', action.props.current!);
+
+        return {
+          ...state,
+          open: true,
+          highlightedValue: itemToHighlight,
+        };
+      }
+
+      if (action.key === 'ArrowUp') {
+        const itemToHighlight =
+          state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'end', action.props.current!);
+
+        return {
+          ...state,
+          open: true,
+          highlightedValue: itemToHighlight,
+        };
+      }
+
+      break;
+
+    default:
+      break;
+  }
+
+  const newState: SelectInternalState<OptionValue> = listReducer(
+    state,
+    action as ListAction<OptionValue, SelectInternalState<OptionValue>> &
+      ListActionAddOn<OptionValue>,
+  );
+
+  switch (action.type) {
+    case ListActionTypes.keyDown:
+      if (
+        !actionMultiple &&
+        (action.event.key === 'Enter' || action.event.key === ' ' || action.event.key === 'Escape')
+      ) {
+        return {
+          ...newState,
+          open: false,
+        };
+      }
+
+      break;
+
+    case ListActionTypes.itemClick:
+      if (!actionMultiple) {
+        return {
+          ...newState,
+          open: false,
+        };
+      }
+
+      break;
+
+    case ListActionTypes.blur:
+      return {
+        ...newState,
+        open: false,
+      };
+
+    default:
+      return newState;
+  }
+
+  return newState;
+}
diff --git a/packages/mui-base/src/useSelect/useSelect.test.tsx b/packages/mui-base/src/useSelect/useSelect.test.tsx
index 36cb26f7c86683..8c0eee25c5e3c2 100644
--- a/packages/mui-base/src/useSelect/useSelect.test.tsx
+++ b/packages/mui-base/src/useSelect/useSelect.test.tsx
@@ -1,2 +1,23 @@
-// TODO: test it properly
-describe('useSelect', () => {});
+import { expect } from 'chai';
+import { renderHook } from '@testing-library/react';
+import useSelect from './useSelect';
+
+describe('useSelect', () => {
+  describe('param: options', () => {
+    it('lets define options explicitly', () => {
+      const options = [
+        { value: 'a', label: 'A' },
+        { value: 'b', label: 'B' },
+        { value: 'c', label: 'C', disabled: true },
+      ];
+
+      const { result } = renderHook(() => useSelect({ options }));
+
+      expect(result.current.options).to.deep.equal(['a', 'b', 'c']);
+      expect(result.current.getOptionMetadata('a')?.label).to.equal('A');
+      expect(result.current.getOptionMetadata('b')?.label).to.equal('B');
+      expect(result.current.getOptionMetadata('c')?.label).to.equal('C');
+      expect(result.current.getOptionMetadata('c')?.disabled).to.equal(true);
+    });
+  });
+});
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 456a0ad9f7025c..a9dd7cb6c8cde1 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -16,19 +16,13 @@ import {
   UseSelectParameters,
   UseSelectReturnValue,
 } from './useSelect.types';
-import useList, {
-  listReducer,
-  ListActionTypes,
-  UseListParameters,
-  ListAction,
-  ListActionAddOn,
-  moveHighlight,
-} from '../useList';
+import useList, { UseListParameters } from '../useList';
 import { EventHandlers } from '../utils/types';
 import defaultOptionStringifier from './defaultOptionStringifier';
 import { SelectProviderValue } from './SelectProvider';
 import { useCompoundParent } from '../utils/useCompound';
 import { SelectOption } from '../useOption/useOption.types';
+import selectReducer from './selectReducer';
 
 /**
  *
@@ -126,105 +120,6 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
 
   const handleListboxRef = useForkRef(listboxRefProp, listboxRef, focusListboxIfRequested);
 
-  const stateReducer = React.useCallback(
-    (
-      state: SelectInternalState<OptionValue>,
-      action: (ListAction<OptionValue, SelectInternalState<OptionValue>> | SelectAction) &
-        ListActionAddOn<OptionValue>,
-    ) => {
-      const { open } = state;
-
-      switch (action.type) {
-        case SelectActionTypes.buttonClick: {
-          const itemToHighlight =
-            state.selectedValues[0] ??
-            moveHighlight<OptionValue>(null, 'start', action.props.current!);
-
-          return {
-            ...state,
-            open: !open,
-            highlightedValue: !open ? itemToHighlight : null,
-          };
-        }
-
-        case SelectActionTypes.buttonArrowKeyDown:
-          if (action.event.key === 'ArrowDown') {
-            const itemToHighlight =
-              state.selectedValues[0] ??
-              moveHighlight<OptionValue>(null, 'start', action.props.current!);
-
-            return {
-              ...state,
-              open: true,
-              highlightedValue: itemToHighlight,
-            };
-          }
-
-          if (action.event.key === 'ArrowUp') {
-            const itemToHighlight =
-              state.selectedValues[0] ??
-              moveHighlight<OptionValue>(null, 'end', action.props.current!);
-
-            return {
-              ...state,
-              open: true,
-              highlightedValue: itemToHighlight,
-            };
-          }
-
-          break;
-
-        default:
-          break;
-      }
-
-      const newState: SelectInternalState<OptionValue> = listReducer(
-        state,
-        action as ListAction<OptionValue, SelectInternalState<OptionValue>> &
-          ListActionAddOn<OptionValue>,
-      );
-
-      switch (action.type) {
-        case ListActionTypes.keyDown:
-          if (
-            !multiple &&
-            (action.event.key === 'Enter' ||
-              action.event.key === ' ' ||
-              action.event.key === 'Escape')
-          ) {
-            return {
-              ...newState,
-              open: false,
-            };
-          }
-
-          break;
-
-        case ListActionTypes.itemClick:
-          if (!multiple) {
-            return {
-              ...newState,
-              open: false,
-            };
-          }
-
-          break;
-
-        case ListActionTypes.blur:
-          return {
-            ...newState,
-            open: false,
-          };
-
-        default:
-          return newState;
-      }
-
-      return newState;
-    },
-    [multiple],
-  );
-
   const {
     getRootProps: getButtonRootProps,
     active: buttonActive,
@@ -267,7 +162,8 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
   const useListParameters: UseListParameters<
     OptionValue,
     SelectInternalState<OptionValue>,
-    SelectAction
+    SelectAction,
+    { multiple: boolean }
   > = {
     getInitialState: () => ({
       highlightedValue: null,
@@ -296,10 +192,11 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
         }
       }
     },
+    reducerActionAddon: React.useMemo(() => ({ multiple }), [multiple]),
     items: optionValues,
     itemStringifier: stringifyOption,
     selectionLimit: multiple ? null : 1,
-    stateReducer,
+    stateReducer: selectReducer,
   };
 
   const {
@@ -356,7 +253,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
 
       if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
         event.preventDefault();
-        dispatch({ type: SelectActionTypes.buttonArrowKeyDown, event });
+        dispatch({ type: SelectActionTypes.buttonArrowKeyDown, key: event.key, event });
       }
     };
 
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 3eab7c4925a85e..58474d7d053841 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -195,6 +195,7 @@ export interface ButtonClickAction {
 
 export interface ButtonArrowKeyDownAction {
   type: typeof ACTION_TYPES_BUTTON_ARROW_KEY_DOWN;
+  key: string;
   event: React.KeyboardEvent;
 }
 
diff --git a/packages/mui-base/src/useTabsList/tabsListReducer.ts b/packages/mui-base/src/useTabsList/tabsListReducer.ts
new file mode 100644
index 00000000000000..c1e1d4d8cac8f9
--- /dev/null
+++ b/packages/mui-base/src/useTabsList/tabsListReducer.ts
@@ -0,0 +1,34 @@
+import { ListState, ListAction, ListActionAddOn, listReducer, ListActionTypes } from '../useList';
+
+export default function tabsListReducer(
+  state: ListState<string | number>,
+  action: ListAction<string | number, ListState<string | number>> &
+    ListActionAddOn<string | number> & { selectionFollowsFocus: boolean },
+) {
+  const newState = listReducer(state, action);
+
+  const { selectionFollowsFocus } = action;
+
+  if (action.type === ListActionTypes.itemsChange) {
+    return {
+      ...newState,
+      highlightedValue: newState.selectedValues[0] ?? null,
+    };
+  }
+
+  if (action.type === ListActionTypes.setState && action.value.selectedValues != null) {
+    return {
+      ...newState,
+      highlightedValue: action.value.selectedValues[0],
+    };
+  }
+
+  if (selectionFollowsFocus && newState.highlightedValue != null) {
+    return {
+      ...newState,
+      selectedValues: [newState.highlightedValue],
+    };
+  }
+
+  return newState;
+}
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 59da70377e901b..eaaf73276c73b6 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -8,13 +8,8 @@ import {
 import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
-import useList, {
-  ListActionTypes,
-  listReducer,
-  ListReducer,
-  ListState,
-  UseListParameters,
-} from '../useList';
+import useList, { ListActionTypes, UseListParameters } from '../useList';
+import tabsListReducer from './tabsListReducer';
 
 /**
  *
@@ -74,36 +69,6 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     listOrientation = isRtl ? 'horizontal-rtl' : 'horizontal-ltr';
   }
 
-  const stateReducer: ListReducer<string | number, ListState<string | number>> = React.useCallback(
-    (state, action) => {
-      const newState = listReducer(state, action);
-
-      if (action.type === ListActionTypes.itemsChange) {
-        return {
-          ...newState,
-          highlightedValue: newState.selectedValues[0] ?? null,
-        };
-      }
-
-      if (action.type === ListActionTypes.setState && action.value.selectedValues != null) {
-        return {
-          ...newState,
-          highlightedValue: action.value.selectedValues[0],
-        };
-      }
-
-      if (selectionFollowsFocus && newState.highlightedValue != null) {
-        return {
-          ...newState,
-          selectedValues: [newState.highlightedValue],
-        };
-      }
-
-      return newState;
-    },
-    [selectionFollowsFocus],
-  );
-
   const handleChange = React.useCallback(
     (
       event:
@@ -142,8 +107,12 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     listRef: externalRef,
     onChange: handleChange,
     orientation: listOrientation,
+    reducerActionAddon: React.useMemo(
+      () => ({ selectionFollowsFocus: selectionFollowsFocus || false }),
+      [selectionFollowsFocus],
+    ),
     selectionLimit: 1,
-    stateReducer,
+    stateReducer: tabsListReducer,
   });
 
   React.useEffect(() => {

From e3528fb901fa37d1edace28f2331c3aa2d830e0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Thu, 6 Apr 2023 17:49:48 +0200
Subject: [PATCH 38/49] Open the Joy Select when clicked on the root element

---
 packages/mui-base/src/useSelect/useSelect.ts       | 1 +
 packages/mui-base/src/useSelect/useSelect.types.ts | 7 ++++++-
 packages/mui-joy/src/Select/Select.tsx             | 5 +++--
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index a9dd7cb6c8cde1..4706c72f7190b9 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -356,6 +356,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     buttonActive,
     buttonFocusVisible,
     disabled,
+    dispatch,
     getButtonProps,
     getListboxProps,
     getOptionMetadata,
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index 58474d7d053841..e3eb4f10440176 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { UseButtonRootSlotProps } from '../useButton';
-import { ListState, UseListRootSlotProps } from '../useList';
+import { ListAction, ListState, UseListRootSlotProps } from '../useList';
 import { SelectOption } from '../useOption/useOption.types';
 import { EventHandlers } from '../utils/types';
 import { SelectProviderValue } from './SelectProvider';
@@ -135,6 +135,11 @@ export interface UseSelectReturnValue<Value, Multiple> {
    * If `true`, the select is disabled.
    */
   disabled: boolean;
+  /**
+   * Action dispatcher for the select component.
+   * Allows to programmatically control the select.
+   */
+  dispatch: (action: ListAction<Value, SelectInternalState<Value>> | SelectAction) => void;
   /**
    * Resolver for the button slot's props.
    * @param otherHandlers event handlers for the button slot
diff --git a/packages/mui-joy/src/Select/Select.tsx b/packages/mui-joy/src/Select/Select.tsx
index 6cc916d5480270..5896157bacac79 100644
--- a/packages/mui-joy/src/Select/Select.tsx
+++ b/packages/mui-joy/src/Select/Select.tsx
@@ -7,7 +7,7 @@ import PopperUnstyled, {
   PopperUnstyledProps,
   PopperUnstyledTypeMap,
 } from '@mui/base/PopperUnstyled';
-import useSelect, { SelectProvider } from '@mui/base/useSelect';
+import useSelect, { SelectActionTypes, SelectProvider } from '@mui/base/useSelect';
 import { SelectOption } from '@mui/base/useOption';
 import composeClasses from '@mui/base/composeClasses';
 import { StyledList } from '../List/List';
@@ -423,6 +423,7 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
     buttonFocusVisible,
     contextValue,
     disabled,
+    dispatch,
     getButtonProps,
     getListboxProps,
     getOptionMetadata,
@@ -476,7 +477,7 @@ const Select = React.forwardRef(function Select<TValue extends {}>(
         ) {
           // show the popup if user click outside of the button element.
           // the close action is already handled by blur event.
-          handleOpenChange(true);
+          dispatch({ type: SelectActionTypes.buttonClick, event });
         }
         handlers.onMouseDown?.(event);
       },

From 8e14f71ba372bf740beebcb8c19f7bd2de1b4a07 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 11:07:52 +0200
Subject: [PATCH 39/49] Docs and tests

---
 docs/pages/base/api/use-select.json           |   7 +
 .../api-docs/use-select/use-select.json       |   1 +
 .../SelectUnstyled/SelectUnstyled.test.tsx    | 259 +++++++++++++-----
 .../test/integration/SelectUnstyled.test.tsx  |  65 -----
 test/karma.tests.js                           |   7 -
 5 files changed, 196 insertions(+), 143 deletions(-)
 delete mode 100644 packages/mui-base/test/integration/SelectUnstyled.test.tsx

diff --git a/docs/pages/base/api/use-select.json b/docs/pages/base/api/use-select.json
index 1a42b2162b207b..51d3b997a6315c 100644
--- a/docs/pages/base/api/use-select.json
+++ b/docs/pages/base/api/use-select.json
@@ -14,6 +14,13 @@
       "required": true
     },
     "disabled": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
+    "dispatch": {
+      "type": {
+        "name": "(action: ListAction&lt;Value, SelectInternalState&lt;Value&gt;&gt; | SelectAction) =&gt; void",
+        "description": "(action: ListAction&lt;Value, SelectInternalState&lt;Value&gt;&gt; | SelectAction) =&gt; void"
+      },
+      "required": true
+    },
     "getButtonProps": {
       "type": {
         "name": "&lt;OtherHandlers extends EventHandlers = {}&gt;(otherHandlers?: OtherHandlers) =&gt; UseSelectButtonSlotProps&lt;OtherHandlers&gt;",
diff --git a/docs/translations/api-docs/use-select/use-select.json b/docs/translations/api-docs/use-select/use-select.json
index 5255ca1ba6e134..8c89382e26739d 100644
--- a/docs/translations/api-docs/use-select/use-select.json
+++ b/docs/translations/api-docs/use-select/use-select.json
@@ -6,6 +6,7 @@
     "buttonFocusVisible": "If <code>true</code>, the trigger button has a visible focus.",
     "contextValue": "A value to be passed to the <code>SelectProvider</code> component.",
     "disabled": "If <code>true</code>, the select is disabled.",
+    "dispatch": "Action dispatcher for the select component.\nAllows to programmatically control the select.",
     "getButtonProps": "Resolver for the button slot's props.",
     "getListboxProps": "Resolver for the listbox slot's props.",
     "getOptionMetadata": "A function that returns the metadata of an option with a given value.",
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index fdb929d440c98f..d1970880d45680 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -1,7 +1,10 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { spy } from 'sinon';
-import SelectUnstyled, { selectUnstyledClasses } from '@mui/base/SelectUnstyled';
+import SelectUnstyled, {
+  SelectUnstyledListboxSlotProps,
+  selectUnstyledClasses,
+} from '@mui/base/SelectUnstyled';
 import { SelectOption } from '@mui/base/useOption';
 import OptionUnstyled, {
   OptionUnstyledProps,
@@ -357,6 +360,70 @@ describe('<SelectUnstyled />', () => {
       expect(select).to.have.text('1');
       expect(queryByRole('listbox', { hidden: true })).not.toBeVisible();
     });
+
+    it('scrolls to highlighted option so it is visible', function test() {
+      if (/jsdom/.test(window.navigator.userAgent)) {
+        this.skip();
+      }
+
+      // two options are visible at a time
+      const SelectListbox = React.forwardRef(function SelectListbox(
+        props: SelectUnstyledListboxSlotProps<string, false>,
+        ref: React.ForwardedRef<HTMLUListElement>,
+      ) {
+        const { ownerState, ...other } = props;
+        return <ul {...other} ref={ref} style={{ maxHeight: '100px', overflow: 'auto' }} />;
+      });
+
+      const Option = React.forwardRef(function Option(
+        props: { value: string; children?: React.ReactNode },
+        ref: React.Ref<HTMLLIElement>,
+      ) {
+        return (
+          <OptionUnstyled
+            {...props}
+            ref={ref}
+            slotProps={{ root: { style: { height: '50px' } } }}
+          />
+        );
+      });
+
+      const { getByRole } = render(
+        <SelectUnstyled slots={{ listbox: SelectListbox }}>
+          <Option value="1">1</Option>
+          <Option value="2">2</Option>
+          <Option value="3">3</Option>
+          <Option value="4">4</Option>
+          <Option value="5">5</Option>
+          <Option value="6">6</Option>
+        </SelectUnstyled>,
+      );
+
+      const select = getByRole('combobox');
+
+      act(() => {
+        select.focus();
+      });
+
+      fireEvent.keyDown(select, { key: 'ArrowDown' }); // opens the listbox and highlights 1
+
+      const listbox = getByRole('listbox');
+
+      fireEvent.keyDown(listbox, { key: 'ArrowDown' }); // highlights 2
+      expect(listbox.scrollTop).to.equal(0);
+
+      fireEvent.keyDown(listbox, { key: 'ArrowDown' }); // highlights 3
+      expect(listbox.scrollTop).to.equal(50);
+
+      fireEvent.keyDown(listbox, { key: 'ArrowDown' }); // highlights 4
+      expect(listbox.scrollTop).to.equal(100);
+
+      fireEvent.keyDown(listbox, { key: 'ArrowUp' }); // highlights 3
+      expect(listbox.scrollTop).to.equal(100);
+
+      fireEvent.keyDown(listbox, { key: 'ArrowUp' }); // highlights 2
+      expect(listbox.scrollTop).to.equal(50);
+    });
   });
 
   describe('form submission', () => {
@@ -777,6 +844,126 @@ describe('<SelectUnstyled />', () => {
     });
   });
 
+  describe('open/close behavior', () => {
+    it('closes the listbox without selecting an option when focus is lost', () => {
+      const { getByRole, getByTestId } = render(
+        <div>
+          <SelectUnstyled defaultValue={1}>
+            <OptionUnstyled value={1}>1</OptionUnstyled>
+            <OptionUnstyled value={2}>2</OptionUnstyled>
+          </SelectUnstyled>
+          <p data-testid="focus-target" tabIndex={0}>
+            focus target
+          </p>
+        </div>,
+      );
+
+      const select = getByRole('combobox');
+
+      act(() => {
+        select.click();
+      });
+
+      const listbox = getByRole('listbox');
+      userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '2'
+
+      const focusTarget = getByTestId('focus-target');
+      act(() => {
+        focusTarget.focus();
+      });
+
+      expect(select).to.have.attribute('aria-expanded', 'false');
+      expect(select).to.have.text('1');
+      expect(listbox).not.toBeVisible();
+    });
+
+    it('closes the listbox when already selected option is selected again with a click', () => {
+      const { getByRole, getByTestId } = render(
+        <SelectUnstyled defaultValue={1}>
+          <OptionUnstyled data-testid="selected-option" value={1}>
+            1
+          </OptionUnstyled>
+          <OptionUnstyled value={2}>2</OptionUnstyled>
+        </SelectUnstyled>,
+      );
+
+      const select = getByRole('combobox');
+
+      act(() => {
+        select.click();
+      });
+
+      const selectedOption = getByTestId('selected-option');
+      fireEvent.click(selectedOption);
+
+      expect(select).to.have.attribute('aria-expanded', 'false');
+      expect(select).to.have.text('1');
+    });
+
+    it('focuses the listbox after it is opened', () => {
+      const { getByRole } = render(
+        <SelectUnstyled>
+          <OptionUnstyled value={1}>1</OptionUnstyled>
+        </SelectUnstyled>,
+      );
+
+      const select = getByRole('combobox');
+      act(() => {
+        select.click();
+      });
+
+      expect(document.activeElement).to.equal(getByRole('listbox'));
+    });
+
+    it('scrolls to initially highlighted option after opening', function test() {
+      if (/jsdom/.test(window.navigator.userAgent)) {
+        this.skip();
+      }
+
+      // two options are visible at a time
+      const SelectListbox = React.forwardRef(function SelectListbox(
+        props: SelectUnstyledListboxSlotProps<string, false>,
+        ref: React.ForwardedRef<HTMLUListElement>,
+      ) {
+        const { ownerState, ...other } = props;
+        return <ul {...other} ref={ref} style={{ maxHeight: '100px', overflow: 'auto' }} />;
+      });
+
+      const Option = React.forwardRef(function Option(
+        props: { value: string; children?: React.ReactNode },
+        ref: React.Ref<HTMLLIElement>,
+      ) {
+        return (
+          <OptionUnstyled
+            {...props}
+            ref={ref}
+            slotProps={{ root: { style: { height: '50px' } } }}
+          />
+        );
+      });
+
+      const { getByRole } = render(
+        <SelectUnstyled slots={{ listbox: SelectListbox }} defaultValue={'4'}>
+          <Option value="1">1</Option>
+          <Option value="2">2</Option>
+          <Option value="3">3</Option>
+          <Option value="4">4</Option>
+          <Option value="5">5</Option>
+          <Option value="6">6</Option>
+        </SelectUnstyled>,
+      );
+
+      const select = getByRole('combobox');
+
+      act(() => {
+        select.click();
+      });
+
+      const listbox = getByRole('listbox');
+      expect(listbox.scrollTop).to.equal(100);
+    });
+  });
+
   it('sets a value correctly when interacted by a user and external code', () => {
     function TestComponent() {
       const [value, setValue] = React.useState<number[]>([]);
@@ -815,74 +1002,4 @@ describe('<SelectUnstyled />', () => {
 
     expect(selectButton).to.have.text('1, 2');
   });
-
-  it('closes the listbox without selecting an option when focus is lost', () => {
-    const { getByRole, getByTestId } = render(
-      <div>
-        <SelectUnstyled defaultValue={1}>
-          <OptionUnstyled value={1}>1</OptionUnstyled>
-          <OptionUnstyled value={2}>2</OptionUnstyled>
-        </SelectUnstyled>
-        <p data-testid="focus-target" tabIndex={0}>
-          focus target
-        </p>
-      </div>,
-    );
-
-    const select = getByRole('combobox');
-
-    act(() => {
-      select.click();
-    });
-
-    const listbox = getByRole('listbox');
-    userEvent.keyPress(listbox, { key: 'ArrowDown' }); // highlights '2'
-
-    const focusTarget = getByTestId('focus-target');
-    act(() => {
-      focusTarget.focus();
-    });
-
-    expect(select).to.have.attribute('aria-expanded', 'false');
-    expect(select).to.have.text('1');
-    expect(listbox).not.toBeVisible();
-  });
-
-  it('closes the listbox when already selected option is selected again with a click', () => {
-    const { getByRole, getByTestId } = render(
-      <SelectUnstyled defaultValue={1}>
-        <OptionUnstyled data-testid="selected-option" value={1}>
-          1
-        </OptionUnstyled>
-        <OptionUnstyled value={2}>2</OptionUnstyled>
-      </SelectUnstyled>,
-    );
-
-    const select = getByRole('combobox');
-
-    act(() => {
-      select.click();
-    });
-
-    const selectedOption = getByTestId('selected-option');
-    fireEvent.click(selectedOption);
-
-    expect(select).to.have.attribute('aria-expanded', 'false');
-    expect(select).to.have.text('1');
-  });
-
-  it('focuses the listbox after it is opened', () => {
-    const { getByRole } = render(
-      <SelectUnstyled>
-        <OptionUnstyled value={1}>1</OptionUnstyled>
-      </SelectUnstyled>,
-    );
-
-    const select = getByRole('combobox');
-    act(() => {
-      select.click();
-    });
-
-    expect(document.activeElement).to.equal(getByRole('listbox'));
-  });
 });
diff --git a/packages/mui-base/test/integration/SelectUnstyled.test.tsx b/packages/mui-base/test/integration/SelectUnstyled.test.tsx
deleted file mode 100644
index 5edb5ea778e199..00000000000000
--- a/packages/mui-base/test/integration/SelectUnstyled.test.tsx
+++ /dev/null
@@ -1,65 +0,0 @@
-import * as React from 'react';
-import { expect } from 'chai';
-import { act, createRenderer, fireEvent } from 'test/utils';
-import OptionUnstyled from '@mui/base/OptionUnstyled';
-import SelectUnstyled, { SelectUnstyledListboxSlotProps } from '@mui/base/SelectUnstyled';
-
-describe('<SelectUnstyled> integration', () => {
-  const { render } = createRenderer();
-
-  it('should scroll to highlighted option so it is visible', function test() {
-    if (/jsdom/.test(window.navigator.userAgent)) {
-      this.skip();
-    }
-
-    const SelectListbox = React.forwardRef(function SelectListbox(
-      props: SelectUnstyledListboxSlotProps<string, false>,
-      ref: React.ForwardedRef<HTMLUListElement>,
-    ) {
-      const { ownerState, ...other } = props;
-      return <ul {...other} ref={ref} style={{ maxHeight: '100px', overflow: 'auto' }} />;
-    });
-
-    const Option = React.forwardRef(function Option(
-      props: { value: string; children?: React.ReactNode },
-      ref: React.Ref<HTMLLIElement>,
-    ) {
-      return (
-        <OptionUnstyled {...props} ref={ref} slotProps={{ root: { style: { height: '50px' } } }} />
-      );
-    });
-
-    const { getByRole } = render(
-      <SelectUnstyled slots={{ listbox: SelectListbox }}>
-        <Option value="1">1</Option>
-        <Option value="2">2</Option>
-        <Option value="3">3</Option>
-        <Option value="4">4</Option>
-        <Option value="5">5</Option>
-        <Option value="6">6</Option>
-      </SelectUnstyled>,
-    );
-
-    const select = getByRole('combobox');
-
-    act(() => {
-      select.focus();
-    });
-
-    fireEvent.keyDown(select, { key: 'ArrowDown' });
-
-    const listbox = getByRole('listbox');
-
-    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
-    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
-    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
-    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
-
-    expect(listbox.scrollTop).to.equal(100);
-
-    fireEvent.keyDown(listbox, { key: 'ArrowUp' });
-    fireEvent.keyDown(listbox, { key: 'ArrowUp' });
-
-    expect(listbox.scrollTop).to.equal(50);
-  });
-});
diff --git a/test/karma.tests.js b/test/karma.tests.js
index 36208528532b97..4625479c8dea4c 100644
--- a/test/karma.tests.js
+++ b/test/karma.tests.js
@@ -8,13 +8,6 @@ const materialIntegrationContext = require.context(
 );
 materialIntegrationContext.keys().forEach(materialIntegrationContext);
 
-const baseIntegrationContext = require.context(
-  '../packages/mui-base/test/integration',
-  true,
-  /\.test\.(js|ts|tsx)$/,
-);
-baseIntegrationContext.keys().forEach(baseIntegrationContext);
-
 const materialUnitContext = require.context(
   '../packages/mui-material/src/',
   true,

From d18aee7b012d7d15d5233a946e62e7f3dbda14ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 14:45:54 +0200
Subject: [PATCH 40/49] Simplify action addon (do not require a ref)

---
 .../mui-base/src/useList/listReducer.test.ts  | 514 ++++++++----------
 packages/mui-base/src/useList/listReducer.ts  |  20 +-
 packages/mui-base/src/useList/useList.ts      |  49 +-
 .../mui-base/src/useList/useList.types.ts     |  12 +-
 packages/mui-base/src/useMenu/menuReducer.ts  |  11 +-
 .../src/useSelect/selectReducer.test.ts       |  75 ++-
 .../mui-base/src/useSelect/selectReducer.ts   |  24 +-
 .../src/useTabsList/tabsListReducer.ts        |  12 +-
 .../mui-base/src/useTabsList/useTabsList.ts   |  20 +-
 .../src/useTabsList/useTabsList.types.ts      |   6 +
 .../src/utils/useControllableReducer.test.tsx |   6 +-
 .../src/utils/useControllableReducer.ts       |  11 +-
 .../src/utils/useControllableReducer.types.ts |  10 +-
 13 files changed, 354 insertions(+), 416 deletions(-)

diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index 0393e166785a55..6aed577a120a23 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -16,19 +16,17 @@ describe('listReducer', () => {
         type: ListActionTypes.setState,
         value: { selectedValues: ['foo'] },
         event: null,
-        props: {
-          current: {
-            items: ['foo', 'bar'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['foo', 'bar'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
       const result = listReducer(state, action);
@@ -46,19 +44,17 @@ describe('listReducer', () => {
       const action: ListReducerAction<string, ListState<string>> = {
         type: ListActionTypes.blur,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            items: [],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: [],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -77,19 +73,17 @@ describe('listReducer', () => {
       const action: ListReducerAction<string, ListState<string>> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
         item: 'two',
       };
@@ -107,19 +101,17 @@ describe('listReducer', () => {
       const action: ListReducerAction<string, ListState<string>> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: 1,
-          },
+        context: {
+          items: ['one', 'two', 'three'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: 1,
         },
         item: 'two',
       };
@@ -137,19 +129,17 @@ describe('listReducer', () => {
       const action: ListReducerAction<string, ListState<string>> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
         item: 'two',
       };
@@ -168,19 +158,17 @@ describe('listReducer', () => {
         type: ListActionTypes.itemClick,
         event: {} as any,
         item: 'three',
-        props: {
-          current: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: 2,
-          },
+        context: {
+          items: ['one', 'two', 'three'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: 2,
         },
       };
 
@@ -197,19 +185,17 @@ describe('listReducer', () => {
       const action: ListReducerAction<string, ListState<string>> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
         item: 'two',
       };
@@ -609,19 +595,17 @@ describe('listReducer', () => {
             type: ListActionTypes.keyDown,
             key: spec.key,
             event: null as any, // not relevant
-            props: {
-              current: {
-                items: ['1', '2', '3', '4', '5'],
-                disableListWrap: spec.disableListWrap,
-                disabledItemsFocusable: spec.disabledItemFocusable,
-                focusManagement: 'activeDescendant',
-                isItemDisabled: (item) => spec.disabledItems.includes(item),
-                itemComparer: (o, v) => o === v,
-                itemStringifier: (option) => option,
-                orientation: 'vertical',
-                pageSize: 3,
-                selectionLimit: null,
-              },
+            context: {
+              items: ['1', '2', '3', '4', '5'],
+              disableListWrap: spec.disableListWrap,
+              disabledItemsFocusable: spec.disabledItemFocusable,
+              focusManagement: 'activeDescendant',
+              isItemDisabled: (item) => spec.disabledItems.includes(item),
+              itemComparer: (o, v) => o === v,
+              itemStringifier: (option) => option,
+              orientation: 'vertical',
+              pageSize: 3,
+              selectionLimit: null,
             },
           };
 
@@ -642,19 +626,17 @@ describe('listReducer', () => {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: () => false,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              pageSize: 5,
-              selectionLimit: null,
-            },
+          context: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            pageSize: 5,
+            selectionLimit: null,
           },
         };
 
@@ -672,19 +654,17 @@ describe('listReducer', () => {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: () => false,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              pageSize: 5,
-              selectionLimit: 1,
-            },
+          context: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            pageSize: 5,
+            selectionLimit: 1,
           },
         };
 
@@ -702,19 +682,17 @@ describe('listReducer', () => {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: () => false,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              pageSize: 5,
-              selectionLimit: null,
-            },
+          context: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            pageSize: 5,
+            selectionLimit: null,
           },
         };
 
@@ -732,19 +710,17 @@ describe('listReducer', () => {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
-          props: {
-            current: {
-              items: ['one', 'two', 'three'],
-              disableListWrap: false,
-              disabledItemsFocusable: false,
-              focusManagement: 'activeDescendant',
-              isItemDisabled: () => false,
-              itemComparer: (o, v) => o === v,
-              itemStringifier: (option) => option,
-              orientation: 'vertical',
-              pageSize: 5,
-              selectionLimit: 2,
-            },
+          context: {
+            items: ['one', 'two', 'three'],
+            disableListWrap: false,
+            disabledItemsFocusable: false,
+            focusManagement: 'activeDescendant',
+            isItemDisabled: () => false,
+            itemComparer: (o, v) => o === v,
+            itemStringifier: (option) => option,
+            orientation: 'vertical',
+            pageSize: 5,
+            selectionLimit: 2,
           },
         };
 
@@ -765,19 +741,17 @@ describe('listReducer', () => {
         type: ListActionTypes.textNavigation,
         searchString: 'th',
         event: {} as React.KeyboardEvent,
-        props: {
-          current: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three', 'four', 'five'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -795,19 +769,17 @@ describe('listReducer', () => {
         type: ListActionTypes.textNavigation,
         searchString: 'z',
         event: {} as React.KeyboardEvent,
-        props: {
-          current: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three', 'four', 'five'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -825,19 +797,17 @@ describe('listReducer', () => {
         type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
-        props: {
-          current: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: (_, i) => i === 1,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three', 'four', 'five'],
+          disableListWrap: false,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: (_, i) => i === 1,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -855,19 +825,17 @@ describe('listReducer', () => {
         type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
-        props: {
-          current: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: false,
-            disabledItemsFocusable: true,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: (_, i) => i === 1,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three', 'four', 'five'],
+          disableListWrap: false,
+          disabledItemsFocusable: true,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: (_, i) => i === 1,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -885,19 +853,17 @@ describe('listReducer', () => {
         type: ListActionTypes.textNavigation,
         searchString: 'one',
         event: {} as React.KeyboardEvent,
-        props: {
-          current: {
-            items: ['one', 'two', 'three', 'four', 'five'],
-            disableListWrap: true,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: null,
-          },
+        context: {
+          items: ['one', 'two', 'three', 'four', 'five'],
+          disableListWrap: true,
+          disabledItemsFocusable: false,
+          focusManagement: 'activeDescendant',
+          isItemDisabled: () => false,
+          itemComparer: (o, v) => o === v,
+          itemStringifier: (option) => option,
+          orientation: 'vertical',
+          pageSize: 5,
+          selectionLimit: null,
         },
       };
 
@@ -930,12 +896,10 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2'],
           previousItems: ['0', '1', '2'],
-          props: {
-            current: {
-              items: ['1', '2'],
-              itemComparer: (o, v) => o === v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: ['1', '2'],
+            itemComparer: (o, v) => o === v,
+            ...irrelevantConfig,
           },
         };
 
@@ -954,12 +918,10 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2'],
           previousItems: ['0', '1', '2'],
-          props: {
-            current: {
-              items: ['1', '2'],
-              itemComparer: (o, v) => o === v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: ['1', '2'],
+            itemComparer: (o, v) => o === v,
+            ...irrelevantConfig,
           },
         };
 
@@ -978,12 +940,10 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2'],
           previousItems: ['0', '1', '2'],
-          props: {
-            current: {
-              items: ['1', '2'],
-              itemComparer: (o, v) => o === v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: ['1', '2'],
+            itemComparer: (o, v) => o === v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1002,12 +962,10 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2'],
           previousItems: ['0', '1', '2'],
-          props: {
-            current: {
-              items: ['1', '2'],
-              itemComparer: (o, v) => o === v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: ['1', '2'],
+            itemComparer: (o, v) => o === v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1029,12 +987,10 @@ describe('listReducer', () => {
           event: null,
           items: [{ v: '1' }, { v: '2' }],
           previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          props: {
-            current: {
-              items: [{ v: '1' }, { v: '2' }],
-              itemComparer: (a, b) => a.v === b.v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: [{ v: '1' }, { v: '2' }],
+            itemComparer: (a, b) => a.v === b.v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1053,12 +1009,10 @@ describe('listReducer', () => {
           event: null,
           items: [{ v: '1' }, { v: '2' }],
           previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          props: {
-            current: {
-              items: [{ v: '1' }, { v: '2' }],
-              itemComparer: (a, b) => a.v === b.v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: [{ v: '1' }, { v: '2' }],
+            itemComparer: (a, b) => a.v === b.v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1077,12 +1031,10 @@ describe('listReducer', () => {
           event: null,
           items: [{ v: '1' }, { v: '2' }],
           previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          props: {
-            current: {
-              items: [{ v: '1' }, { v: '2' }],
-              itemComparer: (a, b) => a.v === b.v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: [{ v: '1' }, { v: '2' }],
+            itemComparer: (a, b) => a.v === b.v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1101,12 +1053,10 @@ describe('listReducer', () => {
           event: null,
           items: [{ v: '1' }, { v: '2' }],
           previousItems: [{ v: '0' }, { v: '1' }, { v: '2' }],
-          props: {
-            current: {
-              items: [{ v: '1' }, { v: '2' }],
-              itemComparer: (a, b) => a.v === b.v,
-              ...irrelevantConfig,
-            },
+          context: {
+            items: [{ v: '1' }, { v: '2' }],
+            itemComparer: (a, b) => a.v === b.v,
+            ...irrelevantConfig,
           },
         };
 
@@ -1127,13 +1077,11 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2'],
           previousItems: [],
-          props: {
-            current: {
-              ...irrelevantConfig,
-              items: ['1', '2'],
-              itemComparer: (o, v) => o === v,
-              focusManagement: 'DOM',
-            },
+          context: {
+            ...irrelevantConfig,
+            items: ['1', '2'],
+            itemComparer: (o, v) => o === v,
+            focusManagement: 'DOM',
           },
         };
 
@@ -1152,14 +1100,12 @@ describe('listReducer', () => {
           event: null,
           items: ['1', '2', '3'],
           previousItems: [],
-          props: {
-            current: {
-              ...irrelevantConfig,
-              items: ['1', '2', '3'],
-              itemComparer: (o, v) => o === v,
-              focusManagement: 'DOM',
-              isItemDisabled: (item) => ['1', '2'].includes(item),
-            },
+          context: {
+            ...irrelevantConfig,
+            items: ['1', '2', '3'],
+            itemComparer: (o, v) => o === v,
+            focusManagement: 'DOM',
+            isItemDisabled: (item) => ['1', '2'].includes(item),
           },
         };
 
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index fbc2fed83666be..f038152c3821a4 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -1,3 +1,4 @@
+import { ActionContext } from '../utils/useControllableReducer.types';
 import { ListActionTypes } from './listActions.types';
 import {
   ListState,
@@ -6,6 +7,10 @@ import {
   ListActionAddOn,
 } from './useList.types';
 
+export type ListActionContext<ItemValue, AdditionalContext> = ActionContext<
+  ListActionAddOn<ItemValue> & AdditionalContext
+>;
+
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
 /**
@@ -428,27 +433,26 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
 
 export default function listReducer<ItemValue, State extends ListState<ItemValue>>(
   state: State,
-  action: ListReducerAction<ItemValue, State> & ListActionAddOn<ItemValue>,
+  action: ListReducerAction<ItemValue, State> & { context: ListActionAddOn<ItemValue> },
 ): State {
-  const { type, props } = action;
-  const parameters = props.current!;
+  const { type, context } = action;
 
   switch (type) {
     case ListActionTypes.keyDown:
-      return handleKeyDown(action.key, state, parameters);
+      return handleKeyDown(action.key, state, context);
     case ListActionTypes.itemClick:
-      return handleItemSelection(action.item, state, parameters);
+      return handleItemSelection(action.item, state, context);
     case ListActionTypes.blur:
-      return handleBlur(state, parameters);
+      return handleBlur(state, context);
     case ListActionTypes.setState:
       return {
         ...state,
         ...action.value,
       };
     case ListActionTypes.textNavigation:
-      return handleTextNavigation(state, action.searchString, parameters);
+      return handleTextNavigation(state, action.searchString, context);
     case ListActionTypes.itemsChange:
-      return handleItemsChange(action.items, action.previousItems, state, parameters);
+      return handleItemsChange(action.items, action.previousItems, state, context);
     default:
       return state;
   }
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index efcddfb217bfc2..59105875c45f34 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -150,8 +150,8 @@ function useList<
     [handleHighlightChange, onChange, onStateChange],
   );
 
-  const propsWithDefaults: React.RefObject<ListActionAddOnValue<ItemValue>> = useLatest(
-    {
+  const reducerContext: ListActionAddOnValue<ItemValue> = React.useMemo(
+    () => ({
       disabledItemsFocusable,
       disableListWrap,
       focusManagement,
@@ -164,16 +164,29 @@ function useList<
       pageSize,
       selectionLimit,
       stateComparers,
-    },
-    [params],
+    }),
+    [
+      disabledItemsFocusable,
+      disableListWrap,
+      focusManagement,
+      isItemDisabled,
+      itemComparer,
+      items,
+      itemStringifier,
+      handleHighlightChange,
+      orientation,
+      pageSize,
+      selectionLimit,
+      stateComparers,
+    ],
   );
 
   const initialState = getInitialState();
   const reducer = externalReducer ?? defaultReducer;
 
   const actionAddOn: ListActionAddOn<ItemValue> & CustomActionAddon = React.useMemo(
-    () => ({ ...externalActionAddon, props: propsWithDefaults }),
-    [propsWithDefaults, externalActionAddon],
+    () => ({ ...externalActionAddon, ...reducerContext }),
+    [externalActionAddon, reducerContext],
   );
 
   type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue, State>;
@@ -242,28 +255,6 @@ function useList<
     notifyHighlightChanged(highlightedValue);
   }, [highlightedValue, notifyHighlightChanged]);
 
-  const setSelectedValue = React.useCallback(
-    (values: ItemValue[]) => {
-      dispatch({
-        type: ListActionTypes.setState,
-        event: null,
-        value: { selectedValues: values } as Partial<State>,
-      });
-    },
-    [dispatch],
-  );
-
-  const setHighlightedValue = React.useCallback(
-    (item: ItemValue | null) => {
-      dispatch({
-        type: ListActionTypes.setState,
-        event: null,
-        value: { highlightedValue: item } as Partial<State>,
-      });
-    },
-    [dispatch],
-  );
-
   const createHandleKeyDown =
     (other: Record<string, React.EventHandler<any>>) =>
     (event: React.KeyboardEvent<HTMLElement>) => {
@@ -431,8 +422,6 @@ function useList<
     getRootProps,
     highlightedOption: highlightedValue,
     selectedOptions: selectedValues,
-    setHighlightedValue,
-    setSelectedValue,
     state,
   };
 }
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 1e20b1ac187464..7897202c9676f2 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -2,9 +2,11 @@ import * as React from 'react';
 import { Simplify } from '@mui/types';
 import { ListAction } from './listActions.types';
 import {
+  ActionContext,
   ControllableReducerAction,
   StateChangeCallback,
 } from '../utils/useControllableReducer.types';
+import type { ListActionContext } from './listReducer';
 
 type ListActionAddOnValueRequiredKeys =
   | 'disabledItemsFocusable'
@@ -25,15 +27,14 @@ export type ListActionAddOnValue<ItemValue> = Simplify<
   Required<Pick<UseListParameters<ItemValue, any, any>, ListActionAddOnValueRequiredKeys>>
 >;
 
-export type ListActionAddOn<ItemValue> = {
-  props: React.RefObject<ListActionAddOnValue<ItemValue>>;
-};
+// TODO: not needed
+export type ListActionAddOn<ItemValue> = ListActionAddOnValue<ItemValue>;
 
 export type ListReducerAction<
   ItemValue,
   State extends ListState<ItemValue>,
   CustomActionAddon = {},
-> = ListAction<ItemValue, State> & ListActionAddOn<ItemValue> & CustomActionAddon;
+> = ListAction<ItemValue, State> & ListActionContext<ItemValue, CustomActionAddon>;
 
 export interface ListState<ItemValue> {
   /**
@@ -179,8 +180,7 @@ export interface UseListParameters<
   stateReducer?: (
     state: State,
     action: (ListAction<ItemValue, State> | CustomAction) &
-      ListActionAddOn<ItemValue> &
-      CustomActionAddon,
+      ActionContext<ListActionAddOn<ItemValue> & CustomActionAddon>,
   ) => State;
 }
 
diff --git a/packages/mui-base/src/useMenu/menuReducer.ts b/packages/mui-base/src/useMenu/menuReducer.ts
index cd4e639fd3f8c3..2a61b65b658335 100644
--- a/packages/mui-base/src/useMenu/menuReducer.ts
+++ b/packages/mui-base/src/useMenu/menuReducer.ts
@@ -1,10 +1,11 @@
 import { ListAction, ListActionAddOn, ListActionTypes, listReducer } from '../useList';
+import { ActionContext } from '../utils/useControllableReducer.types';
 import { MenuInternalState } from './useMenu.types';
 
 export default function menuReducer(
   state: MenuInternalState,
   action: ListAction<string, MenuInternalState> &
-    ListActionAddOn<string> & { listboxRef: React.RefObject<HTMLElement> },
+    ActionContext<ListActionAddOn<string> & { listboxRef: React.RefObject<HTMLElement> }>,
 ) {
   if (action.type === ListActionTypes.itemHover || action.type === ListActionTypes.setState) {
     return state;
@@ -13,10 +14,10 @@ export default function menuReducer(
   const newState = listReducer(state, action);
 
   // make sure an item is always highlighted
-  if (newState.highlightedValue === null && action.props.current!.items.length > 0) {
+  if (newState.highlightedValue === null && action.context.items.length > 0) {
     return {
       ...newState,
-      highlightedValue: action.props.current!.items[0],
+      highlightedValue: action.context.items[0],
     };
   }
 
@@ -30,11 +31,11 @@ export default function menuReducer(
   }
 
   if (action.type === ListActionTypes.blur) {
-    if (!action.listboxRef.current?.contains(action.event.relatedTarget)) {
+    if (!action.context.listboxRef.current?.contains(action.event.relatedTarget)) {
       return {
         ...newState,
         open: false,
-        highlightedValue: action.props.current!.items[0],
+        highlightedValue: action.context.items[0],
       };
     }
   }
diff --git a/packages/mui-base/src/useSelect/selectReducer.test.ts b/packages/mui-base/src/useSelect/selectReducer.test.ts
index c1b6fd8acde58f..7d1a39e7598c6e 100644
--- a/packages/mui-base/src/useSelect/selectReducer.test.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.test.ts
@@ -1,7 +1,6 @@
 import { expect } from 'chai';
-import selectReducer from './selectReducer';
+import selectReducer, { SelectActionContext } from './selectReducer';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
-import { ListActionAddOn } from '../useList';
 
 describe('selectReducer', () => {
   const irrelevantConfig = {
@@ -25,13 +24,13 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+      const action: SelectAction & SelectActionContext<unknown> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
-        props: {
-          current: irrelevantConfig,
+        context: {
+          ...irrelevantConfig,
+          multiple: false,
         },
-        multiple: false,
       };
 
       const result = selectReducer(state, action);
@@ -45,13 +44,13 @@ describe('selectReducer', () => {
         open: true,
       };
 
-      const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+      const action: SelectAction & SelectActionContext<unknown> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
-        props: {
-          current: irrelevantConfig,
+        context: {
+          ...irrelevantConfig,
+          multiple: false,
         },
-        multiple: false,
       };
 
       const result = selectReducer(state, action);
@@ -65,16 +64,14 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+      const action: SelectAction & SelectActionContext<string> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            ...irrelevantConfig,
-            items: ['1', '2', '3'],
-          },
+        context: {
+          ...irrelevantConfig,
+          items: ['1', '2', '3'],
+          multiple: false,
         },
-        multiple: false,
       };
 
       const result = selectReducer(state, action);
@@ -88,16 +85,14 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+      const action: SelectAction & SelectActionContext<string> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
-        props: {
-          current: {
-            ...irrelevantConfig,
-            items: ['1', '2', '3'],
-          },
+        context: {
+          ...irrelevantConfig,
+          items: ['1', '2', '3'],
+          multiple: false,
         },
-        multiple: false,
       };
 
       const result = selectReducer(state, action);
@@ -118,14 +113,14 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & ListActionAddOn<unknown> & { multiple: boolean } = {
+          const action: SelectAction & SelectActionContext<unknown> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
-            props: {
-              current: irrelevantConfig,
+            context: {
+              ...irrelevantConfig,
+              multiple: false,
             },
-            multiple: false,
           };
 
           const result = selectReducer(state, action);
@@ -139,17 +134,15 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+          const action: SelectAction & SelectActionContext<string> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
-            props: {
-              current: {
-                ...irrelevantConfig,
-                items: ['1', '2', '3'],
-              },
+            context: {
+              ...irrelevantConfig,
+              items: ['1', '2', '3'],
+              multiple: false,
             },
-            multiple: false,
           };
 
           const result = selectReducer(state, action);
@@ -163,17 +156,15 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & ListActionAddOn<string> & { multiple: boolean } = {
+          const action: SelectAction & SelectActionContext<string> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
-            props: {
-              current: {
-                ...irrelevantConfig,
-                items: ['1', '2', '3'],
-              },
+            context: {
+              ...irrelevantConfig,
+              items: ['1', '2', '3'],
+              multiple: false,
             },
-            multiple: false,
           };
 
           const result = selectReducer(state, action);
diff --git a/packages/mui-base/src/useSelect/selectReducer.ts b/packages/mui-base/src/useSelect/selectReducer.ts
index 991a1bcf0635fb..1da031bfb35f6c 100644
--- a/packages/mui-base/src/useSelect/selectReducer.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.ts
@@ -5,20 +5,27 @@ import {
   listReducer,
   ListActionTypes,
 } from '../useList';
+import { ActionContext } from '../utils/useControllableReducer.types';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
 
+export type SelectActionContext<OptionValue> = ActionContext<
+  ListActionAddOn<OptionValue> & { multiple: boolean }
+>;
+
 export default function selectReducer<OptionValue>(
   state: SelectInternalState<OptionValue>,
   action: (ListAction<OptionValue, SelectInternalState<OptionValue>> | SelectAction) &
-    ListActionAddOn<OptionValue> & { multiple: boolean },
+    SelectActionContext<OptionValue>,
 ) {
   const { open } = state;
-  const { multiple: actionMultiple } = action;
+  const {
+    context: { multiple },
+  } = action;
 
   switch (action.type) {
     case SelectActionTypes.buttonClick: {
       const itemToHighlight =
-        state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'start', action.props.current!);
+        state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'start', action.context);
 
       return {
         ...state,
@@ -30,8 +37,7 @@ export default function selectReducer<OptionValue>(
     case SelectActionTypes.buttonArrowKeyDown:
       if (action.key === 'ArrowDown') {
         const itemToHighlight =
-          state.selectedValues[0] ??
-          moveHighlight<OptionValue>(null, 'start', action.props.current!);
+          state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'start', action.context);
 
         return {
           ...state,
@@ -42,7 +48,7 @@ export default function selectReducer<OptionValue>(
 
       if (action.key === 'ArrowUp') {
         const itemToHighlight =
-          state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'end', action.props.current!);
+          state.selectedValues[0] ?? moveHighlight<OptionValue>(null, 'end', action.context);
 
         return {
           ...state,
@@ -60,13 +66,13 @@ export default function selectReducer<OptionValue>(
   const newState: SelectInternalState<OptionValue> = listReducer(
     state,
     action as ListAction<OptionValue, SelectInternalState<OptionValue>> &
-      ListActionAddOn<OptionValue>,
+      SelectActionContext<OptionValue>,
   );
 
   switch (action.type) {
     case ListActionTypes.keyDown:
       if (
-        !actionMultiple &&
+        !multiple &&
         (action.event.key === 'Enter' || action.event.key === ' ' || action.event.key === 'Escape')
       ) {
         return {
@@ -78,7 +84,7 @@ export default function selectReducer<OptionValue>(
       break;
 
     case ListActionTypes.itemClick:
-      if (!actionMultiple) {
+      if (!multiple) {
         return {
           ...newState,
           open: false,
diff --git a/packages/mui-base/src/useTabsList/tabsListReducer.ts b/packages/mui-base/src/useTabsList/tabsListReducer.ts
index c1e1d4d8cac8f9..657080abc18de6 100644
--- a/packages/mui-base/src/useTabsList/tabsListReducer.ts
+++ b/packages/mui-base/src/useTabsList/tabsListReducer.ts
@@ -1,13 +1,19 @@
 import { ListState, ListAction, ListActionAddOn, listReducer, ListActionTypes } from '../useList';
+import { ActionContext } from '../utils/useControllableReducer.types';
+
+export type TabsListActionContext = ActionContext<
+  ListActionAddOn<string | number> & { selectionFollowsFocus: boolean }
+>;
 
 export default function tabsListReducer(
   state: ListState<string | number>,
-  action: ListAction<string | number, ListState<string | number>> &
-    ListActionAddOn<string | number> & { selectionFollowsFocus: boolean },
+  action: ListAction<string | number, ListState<string | number>> & TabsListActionContext,
 ) {
   const newState = listReducer(state, action);
 
-  const { selectionFollowsFocus } = action;
+  const {
+    context: { selectionFollowsFocus },
+  } = action;
 
   if (action.type === ListActionTypes.itemsChange) {
     return {
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index eaaf73276c73b6..74c5a708625d64 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -8,7 +8,7 @@ import {
 import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
-import useList, { ListActionTypes, UseListParameters } from '../useList';
+import useList, { UseListParameters } from '../useList';
 import tabsListReducer from './tabsListReducer';
 
 /**
@@ -115,23 +115,6 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     stateReducer: tabsListReducer,
   });
 
-  React.useEffect(() => {
-    if (value === undefined) {
-      return;
-    }
-
-    // when a value changes externally, the highlighted value should be synced to it
-    if (value != null) {
-      dispatch({
-        type: ListActionTypes.setState,
-        event: null,
-        value: {
-          highlightedValue: value,
-        },
-      });
-    }
-  }, [dispatch, value]);
-
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabsListRootSlotProps<TOther> => {
@@ -144,6 +127,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
   };
 
   return {
+    dispatch,
     isRtl,
     orientation,
     selectedValue: selectedOptions[0] ?? null,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.types.ts b/packages/mui-base/src/useTabsList/useTabsList.types.ts
index 8c898b10462e3f..3eac060faa460c 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.types.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.types.ts
@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { TabsListProviderValue } from './TabsListProvider';
+import { ListAction, ListState } from '../useList';
 
 export interface UseTabsListParameters {
   /**
@@ -18,6 +19,11 @@ export type UseTabsListRootSlotProps<TOther = {}> = TOther & {
 };
 
 export interface UseTabsListReturnValue {
+  /**
+   * Action dispatcher for the tabs list component.
+   * Allows to programmatically control the tabs list.
+   */
+  dispatch: (action: ListAction<string | number, ListState<string | number>>) => void;
   /**
    * The value of the currently highlighted tab.
    */
diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
index f42311863dd1d3..88297d97268903 100644
--- a/packages/mui-base/src/utils/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -65,7 +65,7 @@ describe('useControllableReducer', () => {
       }
 
       const { container } = render(<TestComponent />);
-      expect(reducer.getCalls()[0].args[1]).to.deep.equal({ ...actionToDispatch });
+      expect(reducer.getCalls()[0].args[1]).to.include({ ...actionToDispatch });
       expect(container.firstChild).to.have.text('BMW 3 (2022)');
     });
   });
@@ -281,12 +281,12 @@ describe('useControllableReducer', () => {
     it('augments actions with the object provided to the reducer', () => {
       const reducer = (
         state: TestState,
-        action: SetStateAction<TestState> & { overrideProductionYear: number },
+        action: SetStateAction<TestState> & { context: { overrideProductionYear: number } },
       ) => {
         return {
           ...state,
           ...action.value,
-          productionYear: action.overrideProductionYear,
+          productionYear: action.context.overrideProductionYear,
         };
       };
 
diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
index 791fe69ba3c34c..049f0f454a658d 100644
--- a/packages/mui-base/src/utils/useControllableReducer.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -1,5 +1,6 @@
 import * as React from 'react';
 import {
+  ActionContext,
   ControllableReducerAction,
   ControllableReducerParameters,
   setStateActionType,
@@ -129,9 +130,9 @@ function useStateChangeDetection<State extends {}>(
 export default function useControllableReducer<
   State extends {},
   Action extends ControllableReducerAction,
-  ActionAddOn = {},
+  ActionContextValue = undefined,
 >(
-  parameters: ControllableReducerParameters<State, Action, ActionAddOn>,
+  parameters: ControllableReducerParameters<State, Action, ActionContextValue>,
 ): [State, (action: Action) => void] {
   const lastActionRef = React.useRef<Action | null>(null);
 
@@ -146,7 +147,7 @@ export default function useControllableReducer<
 
   // The reducer that is passed to React.useReducer is wrapped with a function that augments the state with controlled values.
   const reducerWithControlledState = React.useCallback(
-    (state: State, action: Action & ActionAddOn) => {
+    (state: State, action: Action & ActionContext<ActionContextValue>) => {
       lastActionRef.current = action;
       const controlledState = getControlledState(state, controlledProps);
       return reducer(controlledState, action);
@@ -161,8 +162,8 @@ export default function useControllableReducer<
     (action: Action) => {
       dispatch({
         ...action,
-        ...actionAddOn,
-      } as Action & ActionAddOn);
+        context: actionAddOn,
+      } as Action & ActionContext<ActionContextValue>);
     },
     [actionAddOn],
   );
diff --git a/packages/mui-base/src/utils/useControllableReducer.types.ts b/packages/mui-base/src/utils/useControllableReducer.types.ts
index cbbbae8381c3e4..bb6b2cb2eda76d 100644
--- a/packages/mui-base/src/utils/useControllableReducer.types.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.types.ts
@@ -10,13 +10,17 @@ export type StateChangeCallback<State> = <StateKey extends keyof State>(
   state: State,
 ) => void;
 
+export type ActionContext<Value> = {
+  context: Value;
+};
+
 /**
  * Parameters of the useControllableReducer hook.
  */
 export interface ControllableReducerParameters<
   State,
   Action extends ControllableReducerAction,
-  ActionAddOn = {},
+  ActionContextValue = undefined,
 > {
   /**
    * The reducer function.
@@ -25,7 +29,7 @@ export interface ControllableReducerParameters<
    * @param action The action to dispatch. The action can be augmented with the `actionAddOn`.
    * @returns The updated state.
    */
-  reducer: (state: State, action: Action & ActionAddOn) => State;
+  reducer: (state: State, action: Action & ActionContext<ActionContextValue>) => State;
   /**
    * The controlled props that will override the state items.
    */
@@ -47,7 +51,7 @@ export interface ControllableReducerParameters<
   /**
    * Additional properties that will be added to the action.
    */
-  actionAddOn?: ActionAddOn;
+  actionAddOn?: ActionContextValue;
 }
 
 export const setStateActionType = 'controlledReducer:setState';

From f8da22a0fea6b2958335a6766513a73fc26fe95c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 14:47:57 +0200
Subject: [PATCH 41/49] Remove the unnecessary setState action (and simplify
 many generics)

---
 .../src/MenuUnstyled/MenuUnstyled.types.ts    |  4 +-
 packages/mui-base/src/useList/ListContext.ts  |  8 +-
 .../mui-base/src/useList/listActions.types.ts |  7 +-
 .../mui-base/src/useList/listReducer.test.ts  | 81 +++++----------
 packages/mui-base/src/useList/listReducer.ts  |  7 +-
 packages/mui-base/src/useList/useList.ts      | 39 ++++----
 .../mui-base/src/useList/useList.types.ts     | 11 +--
 .../mui-base/src/useMenu/MenuProvider.tsx     |  5 +-
 packages/mui-base/src/useMenu/menuReducer.ts  |  4 +-
 .../mui-base/src/useMenu/useMenu.types.ts     |  2 +-
 .../mui-base/src/useSelect/SelectProvider.tsx |  5 +-
 .../mui-base/src/useSelect/selectReducer.ts   |  6 +-
 .../mui-base/src/useSelect/useSelect.types.ts | 13 +--
 .../src/useTabsList/TabsListProvider.tsx      |  8 +-
 .../src/useTabsList/tabsListReducer.ts        | 17 ++--
 .../mui-base/src/useTabsList/useTabsList.ts   | 32 +++++-
 .../src/useTabsList/useTabsList.types.ts      | 13 ++-
 .../src/utils/useControllableReducer.test.tsx | 99 +++++--------------
 .../src/utils/useControllableReducer.ts       |  6 --
 .../src/utils/useControllableReducer.types.ts |  8 --
 20 files changed, 148 insertions(+), 227 deletions(-)

diff --git a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
index 93dbfff3985f26..757e0c1a5e78f0 100644
--- a/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
+++ b/packages/mui-base/src/MenuUnstyled/MenuUnstyled.types.ts
@@ -2,14 +2,14 @@ import { OverrideProps } from '@mui/types';
 import * as React from 'react';
 import PopperUnstyled, { PopperUnstyledProps } from '../PopperUnstyled';
 import { SlotComponentProps } from '../utils';
-import { MenuInternalState, UseMenuListboxSlotProps } from '../useMenu';
+import { UseMenuListboxSlotProps } from '../useMenu';
 import { ListAction } from '../useList';
 
 export interface MenuUnstyledRootSlotPropsOverrides {}
 export interface MenuUnstyledListboxSlotPropsOverrides {}
 
 export interface MenuUnstyledActions {
-  dispatch: (action: ListAction<string, MenuInternalState>) => void;
+  dispatch: (action: ListAction<string>) => void;
 }
 
 export interface MenuUnstyledOwnProps {
diff --git a/packages/mui-base/src/useList/ListContext.ts b/packages/mui-base/src/useList/ListContext.ts
index 2484d4b3fff371..f4eb99490fa215 100644
--- a/packages/mui-base/src/useList/ListContext.ts
+++ b/packages/mui-base/src/useList/ListContext.ts
@@ -1,9 +1,9 @@
 import * as React from 'react';
 import { ListAction } from './listActions.types';
-import { ListState, ListItemState } from './useList.types';
+import { ListItemState } from './useList.types';
 
-export interface ListContextValue<ItemValue, State extends ListState<ItemValue>> {
-  dispatch: (action: ListAction<ItemValue, State>) => void;
+export interface ListContextValue<ItemValue> {
+  dispatch: (action: ListAction<ItemValue>) => void;
   getItemState: (item: ItemValue) => ListItemState;
   registerHighlightChangeHandler: (handler: (item: ItemValue | null) => void) => () => void;
   registerSelectionChangeHandler: (
@@ -11,7 +11,7 @@ export interface ListContextValue<ItemValue, State extends ListState<ItemValue>>
   ) => () => void;
 }
 
-export const ListContext = React.createContext<ListContextValue<any, any> | null>(null);
+export const ListContext = React.createContext<ListContextValue<any> | null>(null);
 if (process.env.NODE_ENV !== 'production') {
   ListContext.displayName = 'ListContext';
 }
diff --git a/packages/mui-base/src/useList/listActions.types.ts b/packages/mui-base/src/useList/listActions.types.ts
index f15e8e6e77b0c7..32c696000be93f 100644
--- a/packages/mui-base/src/useList/listActions.types.ts
+++ b/packages/mui-base/src/useList/listActions.types.ts
@@ -1,6 +1,3 @@
-import { SetStateAction, setStateActionType } from '../utils/useControllableReducer.types';
-import type { ListState } from './useList.types';
-
 export const ListActionTypes = {
   blur: 'list:blur',
   focus: 'list:focus',
@@ -8,7 +5,6 @@ export const ListActionTypes = {
   itemClick: 'list:itemClick',
   itemHover: 'list:itemHover',
   itemsChange: 'list:itemsChange',
-  setState: setStateActionType,
   textNavigation: 'list:textNavigation',
 } as const;
 
@@ -53,12 +49,11 @@ interface ItemsChangeAction<ItemValue> {
   previousItems: ItemValue[];
 }
 
-export type ListAction<ItemValue, State extends ListState<ItemValue>> =
+export type ListAction<ItemValue> =
   | BlurAction
   | FocusAction
   | ItemClickAction<ItemValue>
   | ItemHoverAction<ItemValue>
   | ItemsChangeAction<ItemValue>
   | KeyDownAction
-  | SetStateAction<State>
   | TextNavigationAction;
diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index 6aed577a120a23..d4c7b93ef0d176 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -5,35 +5,6 @@ import { ListReducerAction, ListState } from './useList.types';
 import { ListActionTypes } from './listActions.types';
 
 describe('listReducer', () => {
-  describe('action: setControlledValue', () => {
-    it("assigns the provided value to the state's selectedValues", () => {
-      const state: ListState<string> = {
-        highlightedValue: 'a',
-        selectedValues: [],
-      };
-
-      const action: ListReducerAction<string, ListState<string>> = {
-        type: ListActionTypes.setState,
-        value: { selectedValues: ['foo'] },
-        event: null,
-        context: {
-          items: ['foo', 'bar'],
-          disableListWrap: false,
-          disabledItemsFocusable: false,
-          focusManagement: 'activeDescendant',
-          isItemDisabled: () => false,
-          itemComparer: (o, v) => o === v,
-          itemStringifier: (option) => option,
-          orientation: 'vertical',
-          pageSize: 5,
-          selectionLimit: null,
-        },
-      };
-      const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['foo']);
-    });
-  });
-
   describe('action: blur', () => {
     it('resets the highlightedValue', () => {
       const state: ListState<string> = {
@@ -41,7 +12,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.blur,
         event: {} as any, // not relevant
         context: {
@@ -70,7 +41,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         context: {
@@ -98,7 +69,7 @@ describe('listReducer', () => {
         selectedValues: ['one'],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         context: {
@@ -126,7 +97,7 @@ describe('listReducer', () => {
         selectedValues: ['one'],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         context: {
@@ -154,7 +125,7 @@ describe('listReducer', () => {
         selectedValues: ['one', 'two'],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
         event: {} as any,
         item: 'three',
@@ -182,7 +153,7 @@ describe('listReducer', () => {
         selectedValues: ['one', 'two'],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
         event: {} as any, // not relevant
         context: {
@@ -591,7 +562,7 @@ describe('listReducer', () => {
             selectedValues: [],
           };
 
-          const action: ListReducerAction<string, ListState<string>> = {
+          const action: ListReducerAction<string> = {
             type: ListActionTypes.keyDown,
             key: spec.key,
             event: null as any, // not relevant
@@ -622,7 +593,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
@@ -650,7 +621,7 @@ describe('listReducer', () => {
           selectedValues: ['one'],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
@@ -678,7 +649,7 @@ describe('listReducer', () => {
           selectedValues: ['one'],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
@@ -706,7 +677,7 @@ describe('listReducer', () => {
           selectedValues: ['one', 'two'],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.keyDown,
           key: 'Enter',
           event: {} as any,
@@ -737,7 +708,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.textNavigation,
         searchString: 'th',
         event: {} as React.KeyboardEvent,
@@ -765,7 +736,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.textNavigation,
         searchString: 'z',
         event: {} as React.KeyboardEvent,
@@ -793,7 +764,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
@@ -821,7 +792,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.textNavigation,
         searchString: 't',
         event: {} as React.KeyboardEvent,
@@ -849,7 +820,7 @@ describe('listReducer', () => {
         selectedValues: [],
       };
 
-      const action: ListReducerAction<string, ListState<string>> = {
+      const action: ListReducerAction<string> = {
         type: ListActionTypes.textNavigation,
         searchString: 'one',
         event: {} as React.KeyboardEvent,
@@ -891,7 +862,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2'],
@@ -913,7 +884,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2'],
@@ -935,7 +906,7 @@ describe('listReducer', () => {
           selectedValues: ['1', '2'],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2'],
@@ -957,7 +928,7 @@ describe('listReducer', () => {
           selectedValues: ['0', '2'],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2'],
@@ -982,7 +953,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+        const action: ListReducerAction<ItemType> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: [{ v: '1' }, { v: '2' }],
@@ -1004,7 +975,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+        const action: ListReducerAction<ItemType> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: [{ v: '1' }, { v: '2' }],
@@ -1026,7 +997,7 @@ describe('listReducer', () => {
           selectedValues: [{ v: '1' }, { v: '2' }],
         };
 
-        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+        const action: ListReducerAction<ItemType> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: [{ v: '1' }, { v: '2' }],
@@ -1048,7 +1019,7 @@ describe('listReducer', () => {
           selectedValues: [{ v: '0' }, { v: '2' }],
         };
 
-        const action: ListReducerAction<ItemType, ListState<ItemType>> = {
+        const action: ListReducerAction<ItemType> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: [{ v: '1' }, { v: '2' }],
@@ -1072,7 +1043,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2'],
@@ -1095,7 +1066,7 @@ describe('listReducer', () => {
           selectedValues: [],
         };
 
-        const action: ListReducerAction<string, ListState<string>> = {
+        const action: ListReducerAction<string> = {
           type: ListActionTypes.itemsChange,
           event: null,
           items: ['1', '2', '3'],
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index f038152c3821a4..ecdb482b71cf96 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -433,7 +433,7 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
 
 export default function listReducer<ItemValue, State extends ListState<ItemValue>>(
   state: State,
-  action: ListReducerAction<ItemValue, State> & { context: ListActionAddOn<ItemValue> },
+  action: ListReducerAction<ItemValue> & { context: ListActionAddOn<ItemValue> },
 ): State {
   const { type, context } = action;
 
@@ -444,11 +444,6 @@ export default function listReducer<ItemValue, State extends ListState<ItemValue
       return handleItemSelection(action.item, state, context);
     case ListActionTypes.blur:
       return handleBlur(state, context);
-    case ListActionTypes.setState:
-      return {
-        ...state,
-        ...action.value,
-      };
     case ListActionTypes.textNavigation:
       return handleTextNavigation(state, action.searchString, context);
     case ListActionTypes.itemsChange:
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 59105875c45f34..8c2a2443e824ca 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -150,8 +150,8 @@ function useList<
     [handleHighlightChange, onChange, onStateChange],
   );
 
-  const reducerContext: ListActionAddOnValue<ItemValue> = React.useMemo(
-    () => ({
+  const reducerContext: ListActionAddOnValue<ItemValue> = React.useMemo(() => {
+    return {
       disabledItemsFocusable,
       disableListWrap,
       focusManagement,
@@ -164,22 +164,21 @@ function useList<
       pageSize,
       selectionLimit,
       stateComparers,
-    }),
-    [
-      disabledItemsFocusable,
-      disableListWrap,
-      focusManagement,
-      isItemDisabled,
-      itemComparer,
-      items,
-      itemStringifier,
-      handleHighlightChange,
-      orientation,
-      pageSize,
-      selectionLimit,
-      stateComparers,
-    ],
-  );
+    };
+  }, [
+    disabledItemsFocusable,
+    disableListWrap,
+    focusManagement,
+    isItemDisabled,
+    itemComparer,
+    items,
+    itemStringifier,
+    handleHighlightChange,
+    orientation,
+    pageSize,
+    selectionLimit,
+    stateComparers,
+  ]);
 
   const initialState = getInitialState();
   const reducer = externalReducer ?? defaultReducer;
@@ -189,7 +188,7 @@ function useList<
     [externalActionAddon, reducerContext],
   );
 
-  type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue, State>;
+  type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue>;
 
   const [state, dispatch] = useControllableReducer<
     State,
@@ -401,7 +400,7 @@ function useList<
     ],
   );
 
-  const contextValue: ListContextValue<ItemValue, State> = React.useMemo(
+  const contextValue: ListContextValue<ItemValue> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 7897202c9676f2..3a3aba450e6d41 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -30,11 +30,8 @@ export type ListActionAddOnValue<ItemValue> = Simplify<
 // TODO: not needed
 export type ListActionAddOn<ItemValue> = ListActionAddOnValue<ItemValue>;
 
-export type ListReducerAction<
-  ItemValue,
-  State extends ListState<ItemValue>,
-  CustomActionAddon = {},
-> = ListAction<ItemValue, State> & ListActionContext<ItemValue, CustomActionAddon>;
+export type ListReducerAction<ItemValue, CustomActionAddon = {}> = ListAction<ItemValue> &
+  ListActionContext<ItemValue, CustomActionAddon>;
 
 export interface ListState<ItemValue> {
   /**
@@ -49,7 +46,7 @@ export interface ListState<ItemValue> {
 
 export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomActionAddon> = (
   state: State,
-  action: ListReducerAction<ItemValue, State, CustomActionAddon>,
+  action: ListReducerAction<ItemValue, CustomActionAddon>,
 ) => State;
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
@@ -179,7 +176,7 @@ export interface UseListParameters<
    */
   stateReducer?: (
     state: State,
-    action: (ListAction<ItemValue, State> | CustomAction) &
+    action: (ListAction<ItemValue> | CustomAction) &
       ActionContext<ListActionAddOn<ItemValue> & CustomActionAddon>,
   ) => State;
 }
diff --git a/packages/mui-base/src/useMenu/MenuProvider.tsx b/packages/mui-base/src/useMenu/MenuProvider.tsx
index 1ba94b905474af..a6d23c6ebe14a7 100644
--- a/packages/mui-base/src/useMenu/MenuProvider.tsx
+++ b/packages/mui-base/src/useMenu/MenuProvider.tsx
@@ -2,10 +2,9 @@ import * as React from 'react';
 import { ListContext, ListContextValue } from '../useList/ListContext';
 import { MenuItemMetadata } from '../useMenuItem';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
-import type { MenuInternalState } from './useMenu.types';
 
 export type MenuProviderValue = CompoundComponentContextValue<string, MenuItemMetadata> &
-  ListContextValue<string, MenuInternalState>;
+  ListContextValue<string>;
 
 export interface MenuProviderProps {
   value: MenuProviderValue;
@@ -30,7 +29,7 @@ export default function MenuProvider(props: MenuProviderProps) {
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<string, MenuInternalState> = React.useMemo(
+  const listContextValue: ListContextValue<string> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useMenu/menuReducer.ts b/packages/mui-base/src/useMenu/menuReducer.ts
index 2a61b65b658335..2ca8d41392bafb 100644
--- a/packages/mui-base/src/useMenu/menuReducer.ts
+++ b/packages/mui-base/src/useMenu/menuReducer.ts
@@ -4,10 +4,10 @@ import { MenuInternalState } from './useMenu.types';
 
 export default function menuReducer(
   state: MenuInternalState,
-  action: ListAction<string, MenuInternalState> &
+  action: ListAction<string> &
     ActionContext<ListActionAddOn<string> & { listboxRef: React.RefObject<HTMLElement> }>,
 ) {
-  if (action.type === ListActionTypes.itemHover || action.type === ListActionTypes.setState) {
+  if (action.type === ListActionTypes.itemHover) {
     return state;
   }
 
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 05b04eb350b708..586280beb21111 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -38,7 +38,7 @@ export interface UseMenuReturnValue {
    * Action dispatcher for the menu component.
    * Allows to programmatically control the menu.
    */
-  dispatch: (action: ListAction<string, MenuInternalState>) => void;
+  dispatch: (action: ListAction<string>) => void;
   /**
    * Resolver for the listbox component's props.
    * @param otherHandlers event handlers for the listbox component
diff --git a/packages/mui-base/src/useSelect/SelectProvider.tsx b/packages/mui-base/src/useSelect/SelectProvider.tsx
index 8fa41a561df2b0..eb8d54157526e1 100644
--- a/packages/mui-base/src/useSelect/SelectProvider.tsx
+++ b/packages/mui-base/src/useSelect/SelectProvider.tsx
@@ -2,10 +2,9 @@ import * as React from 'react';
 import { ListContextValue, ListContext } from '../useList/ListContext';
 import { SelectOption } from '../useOption/useOption.types';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
-import type { SelectInternalState } from './useSelect.types';
 
 export type SelectProviderValue<Value> = CompoundComponentContextValue<Value, SelectOption<Value>> &
-  ListContextValue<Value, SelectInternalState<Value>>;
+  ListContextValue<Value>;
 
 export interface SelectProviderProps<Value> {
   value: SelectProviderValue<Value>;
@@ -30,7 +29,7 @@ export default function SelectProvider<Value>(props: SelectProviderProps<Value>)
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<Value, SelectInternalState<Value>> = React.useMemo(
+  const listContextValue: ListContextValue<Value> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useSelect/selectReducer.ts b/packages/mui-base/src/useSelect/selectReducer.ts
index 1da031bfb35f6c..3aa3202ebe4275 100644
--- a/packages/mui-base/src/useSelect/selectReducer.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.ts
@@ -14,8 +14,7 @@ export type SelectActionContext<OptionValue> = ActionContext<
 
 export default function selectReducer<OptionValue>(
   state: SelectInternalState<OptionValue>,
-  action: (ListAction<OptionValue, SelectInternalState<OptionValue>> | SelectAction) &
-    SelectActionContext<OptionValue>,
+  action: (ListAction<OptionValue> | SelectAction) & SelectActionContext<OptionValue>,
 ) {
   const { open } = state;
   const {
@@ -65,8 +64,7 @@ export default function selectReducer<OptionValue>(
 
   const newState: SelectInternalState<OptionValue> = listReducer(
     state,
-    action as ListAction<OptionValue, SelectInternalState<OptionValue>> &
-      SelectActionContext<OptionValue>,
+    action as ListAction<OptionValue> & SelectActionContext<OptionValue>,
   );
 
   switch (action.type) {
diff --git a/packages/mui-base/src/useSelect/useSelect.types.ts b/packages/mui-base/src/useSelect/useSelect.types.ts
index e3eb4f10440176..05db83601c1ce7 100644
--- a/packages/mui-base/src/useSelect/useSelect.types.ts
+++ b/packages/mui-base/src/useSelect/useSelect.types.ts
@@ -139,7 +139,7 @@ export interface UseSelectReturnValue<Value, Multiple> {
    * Action dispatcher for the select component.
    * Allows to programmatically control the select.
    */
-  dispatch: (action: ListAction<Value, SelectInternalState<Value>> | SelectAction) => void;
+  dispatch: (action: ListAction<Value> | SelectAction) => void;
   /**
    * Resolver for the button slot's props.
    * @param otherHandlers event handlers for the button slot
@@ -185,21 +185,18 @@ export interface UseSelectReturnValue<Value, Multiple> {
   value: SelectValue<Value, Multiple>;
 }
 
-const ACTION_TYPES_BUTTON_CLICK = 'buttonClick';
-const ACTION_TYPES_BUTTON_ARROW_KEY_DOWN = 'buttonArrowKeyDown';
-
 export const SelectActionTypes = {
-  buttonClick: ACTION_TYPES_BUTTON_CLICK,
-  buttonArrowKeyDown: ACTION_TYPES_BUTTON_ARROW_KEY_DOWN,
+  buttonClick: 'buttonClick',
+  buttonArrowKeyDown: 'buttonArrowKeyDown',
 } as const;
 
 export interface ButtonClickAction {
-  type: typeof ACTION_TYPES_BUTTON_CLICK;
+  type: typeof SelectActionTypes.buttonClick;
   event: React.MouseEvent;
 }
 
 export interface ButtonArrowKeyDownAction {
-  type: typeof ACTION_TYPES_BUTTON_ARROW_KEY_DOWN;
+  type: typeof SelectActionTypes.buttonArrowKeyDown;
   key: string;
   event: React.KeyboardEvent;
 }
diff --git a/packages/mui-base/src/useTabsList/TabsListProvider.tsx b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
index 29e0e49beafcca..fcef5ff3baebe4 100644
--- a/packages/mui-base/src/useTabsList/TabsListProvider.tsx
+++ b/packages/mui-base/src/useTabsList/TabsListProvider.tsx
@@ -1,11 +1,10 @@
 import * as React from 'react';
-import { ListState } from '../useList';
 import { ListContextValue, ListContext } from '../useList/ListContext';
 import { TabMetadata } from '../useTabs/useTabs';
 import { CompoundComponentContext, CompoundComponentContextValue } from '../utils/useCompound';
 
 export type TabsListProviderValue = CompoundComponentContextValue<string | number, TabMetadata> &
-  ListContextValue<string | number, ListState<string | number>>;
+  ListContextValue<string | number>;
 
 export interface TabsListProviderProps {
   value: TabsListProviderValue;
@@ -29,10 +28,7 @@ export default function TabsListProvider(props: TabsListProviderProps) {
     totalSubitemCount,
   } = value;
 
-  const listContextValue: ListContextValue<
-    string | number,
-    ListState<string | number>
-  > = React.useMemo(
+  const listContextValue: ListContextValue<string | number> = React.useMemo(
     () => ({
       dispatch,
       getItemState,
diff --git a/packages/mui-base/src/useTabsList/tabsListReducer.ts b/packages/mui-base/src/useTabsList/tabsListReducer.ts
index 657080abc18de6..75e9905493b245 100644
--- a/packages/mui-base/src/useTabsList/tabsListReducer.ts
+++ b/packages/mui-base/src/useTabsList/tabsListReducer.ts
@@ -1,5 +1,6 @@
 import { ListState, ListAction, ListActionAddOn, listReducer, ListActionTypes } from '../useList';
 import { ActionContext } from '../utils/useControllableReducer.types';
+import { TabsListActionTypes, ValueChangeAction } from './useTabsList.types';
 
 export type TabsListActionContext = ActionContext<
   ListActionAddOn<string | number> & { selectionFollowsFocus: boolean }
@@ -7,8 +8,15 @@ export type TabsListActionContext = ActionContext<
 
 export default function tabsListReducer(
   state: ListState<string | number>,
-  action: ListAction<string | number, ListState<string | number>> & TabsListActionContext,
+  action: (ListAction<string | number> | ValueChangeAction) & TabsListActionContext,
 ) {
+  if (action.type === TabsListActionTypes.valueChange) {
+    return {
+      ...state,
+      highlightedValue: action.value,
+    };
+  }
+
   const newState = listReducer(state, action);
 
   const {
@@ -22,13 +30,6 @@ export default function tabsListReducer(
     };
   }
 
-  if (action.type === ListActionTypes.setState && action.value.selectedValues != null) {
-    return {
-      ...newState,
-      highlightedValue: action.value.selectedValues[0],
-    };
-  }
-
   if (selectionFollowsFocus && newState.highlightedValue != null) {
     return {
       ...newState,
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 74c5a708625d64..d419a407f8c9f1 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -1,14 +1,16 @@
 import * as React from 'react';
 import { useTabsContext } from '../TabsUnstyled';
 import {
+  TabsListActionTypes,
   UseTabsListParameters,
   UseTabsListReturnValue,
   UseTabsListRootSlotProps,
+  ValueChangeAction,
 } from './useTabsList.types';
 import { EventHandlers } from '../utils';
 import { useCompoundParent } from '../utils/useCompound';
 import { TabMetadata } from '../useTabs/useTabs';
-import useList, { UseListParameters } from '../useList';
+import useList, { ListState, UseListParameters } from '../useList';
 import tabsListReducer from './tabsListReducer';
 
 /**
@@ -91,18 +93,28 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     return value != null ? { selectedValues: [value] } : { selectedValues: [] };
   }, [value]);
 
+  const isItemDisabled = React.useCallback(
+    (item: string | number) => subitems.get(item)?.disabled ?? false,
+    [subitems],
+  );
+
   const {
     contextValue: listContextValue,
     dispatch,
     getRootProps: getListboxRootProps,
     highlightedOption,
     selectedOptions,
-  } = useList({
+  } = useList<
+    string | number,
+    ListState<string | number>,
+    ValueChangeAction,
+    { selectionFollowsFocus: boolean }
+  >({
     controlledProps,
     disabledItemsFocusable: !selectionFollowsFocus,
     focusManagement: 'DOM',
     getItemDomElement: getTabElement,
-    isItemDisabled: (item) => subitems.get(item)?.disabled ?? false,
+    isItemDisabled,
     items: subitemKeys,
     listRef: externalRef,
     onChange: handleChange,
@@ -115,6 +127,20 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     stateReducer: tabsListReducer,
   });
 
+  React.useEffect(() => {
+    if (value === undefined) {
+      return;
+    }
+
+    // when a value changes externally, the highlighted value should be synced to it
+    if (value != null) {
+      dispatch({
+        type: TabsListActionTypes.valueChange,
+        value,
+      });
+    }
+  }, [dispatch, value]);
+
   const getRootProps = <TOther extends EventHandlers = {}>(
     otherHandlers: TOther = {} as TOther,
   ): UseTabsListRootSlotProps<TOther> => {
diff --git a/packages/mui-base/src/useTabsList/useTabsList.types.ts b/packages/mui-base/src/useTabsList/useTabsList.types.ts
index 3eac060faa460c..c5556bbe9c5b05 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.types.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.types.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { TabsListProviderValue } from './TabsListProvider';
-import { ListAction, ListState } from '../useList';
+import { ListAction } from '../useList';
 
 export interface UseTabsListParameters {
   /**
@@ -23,7 +23,7 @@ export interface UseTabsListReturnValue {
    * Action dispatcher for the tabs list component.
    * Allows to programmatically control the tabs list.
    */
-  dispatch: (action: ListAction<string | number, ListState<string | number>>) => void;
+  dispatch: (action: ListAction<string | number>) => void;
   /**
    * The value of the currently highlighted tab.
    */
@@ -55,3 +55,12 @@ export interface UseTabsListReturnValue {
    */
   contextValue: TabsListProviderValue;
 }
+
+export const TabsListActionTypes = {
+  valueChange: 'valueChange',
+} as const;
+
+export interface ValueChangeAction {
+  type: typeof TabsListActionTypes.valueChange;
+  value: string | number | null;
+}
diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
index 88297d97268903..f00a47fa6988fe 100644
--- a/packages/mui-base/src/utils/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -3,11 +3,7 @@ import * as React from 'react';
 import { spy } from 'sinon';
 import { createRenderer } from 'test/utils';
 import useControllableReducer from './useControllableReducer';
-import {
-  ControllableReducerParameters,
-  SetStateAction,
-  setStateActionType,
-} from './useControllableReducer.types';
+import { ControllableReducerParameters } from './useControllableReducer.types';
 
 interface TestState {
   make: string;
@@ -16,6 +12,11 @@ interface TestState {
   features?: string[];
 }
 
+interface SetMakeAction {
+  type: 'setMake';
+  value: string;
+}
+
 interface UpdateProductionYearAction {
   type: 'updateProductionYear';
   value: number;
@@ -32,23 +33,19 @@ describe('useControllableReducer', () => {
 
   describe('param: reducer', () => {
     it('calls the provided reducer', () => {
-      const reducer = spy((state: TestState, action: SetStateAction<TestState>) => {
+      const reducer = spy((state: TestState, action: SetMakeAction) => {
         return {
           ...state,
-          ...action.value,
+          make: action.value,
         };
       });
 
-      const actionToDispatch: SetStateAction<TestState> = {
-        type: setStateActionType,
-        value: { make: 'BMW' },
-        event: null,
+      const actionToDispatch: SetMakeAction = {
+        type: 'setMake',
+        value: 'BMW',
       };
 
-      const reducerParameters: ControllableReducerParameters<
-        TestState,
-        SetStateAction<TestState>
-      > = {
+      const reducerParameters: ControllableReducerParameters<TestState, SetMakeAction> = {
         reducer,
         controlledProps: {},
         initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
@@ -72,10 +69,7 @@ describe('useControllableReducer', () => {
 
   describe('param: initialProps', () => {
     it('sets the initial state', () => {
-      const reducerParameters: ControllableReducerParameters<
-        TestState,
-        SetStateAction<TestState>
-      > = {
+      const reducerParameters: ControllableReducerParameters<TestState, SetMakeAction> = {
         reducer: (state) => state,
         controlledProps: {},
         initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
@@ -97,32 +91,28 @@ describe('useControllableReducer', () => {
 
   describe('param: controlledProps', () => {
     it('overwrites the state field with the corresponding controlled prop value', () => {
-      const reducer = (state: TestState, action: SetStateAction<TestState>) => {
+      const reducer = (state: TestState, action: SetMakeAction) => {
         // Even though the initial state is set to 'Mazda', the controlled prop overwrites it.
         expect(state.make).to.equal('Tesla');
 
         return {
           ...state,
-          ...action.value,
+          make: action.value,
         };
       };
 
-      const actionToDispatch: SetStateAction<TestState> = {
-        type: setStateActionType,
-        value: { make: 'BMW' },
-        event: null,
+      const actionToDispatch: SetMakeAction = {
+        type: 'setMake',
+        value: 'BMW',
       };
 
-      const reducerParameters: ControllableReducerParameters<
-        TestState,
-        SetStateAction<TestState>
-      > = {
+      const reducerParameters: ControllableReducerParameters<TestState, SetMakeAction> = {
         reducer,
         initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
       };
 
       function TestComponent(props: { make: string }) {
-        const [state, dispatch] = useControllableReducer<TestState, SetStateAction<TestState>>({
+        const [state, dispatch] = useControllableReducer<TestState, SetMakeAction>({
           ...reducerParameters,
           controlledProps: { make: props.make },
         });
@@ -239,66 +229,29 @@ describe('useControllableReducer', () => {
         },
       ]);
     });
-
-    it('does not call onStateChange when the state is updated via the SetStateAction', () => {
-      const reducer = spy((state: TestState, action: SetStateAction<TestState>) => {
-        return {
-          ...state,
-          ...action.value,
-        };
-      });
-
-      const actionToDispatch: SetStateAction<TestState> = {
-        type: setStateActionType,
-        event: null,
-        value: { productionYear: 2010 },
-      };
-
-      const handleChange = spy();
-
-      const reducerParameters: ControllableReducerParameters<
-        TestState,
-        SetStateAction<TestState>
-      > = {
-        reducer,
-        controlledProps: {},
-        initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
-        onStateChange: handleChange,
-      };
-
-      function TestComponent() {
-        const [, dispatch] = useControllableReducer(reducerParameters);
-        React.useEffect(() => dispatch(actionToDispatch), [dispatch]);
-        return null;
-      }
-
-      render(<TestComponent />);
-      expect(handleChange.called).to.equal(false);
-    });
   });
 
   describe('param: actionAddOn', () => {
     it('augments actions with the object provided to the reducer', () => {
       const reducer = (
         state: TestState,
-        action: SetStateAction<TestState> & { context: { overrideProductionYear: number } },
+        action: UpdateProductionYearAction & { context: { overrideProductionYear: number } },
       ) => {
         return {
           ...state,
-          ...action.value,
           productionYear: action.context.overrideProductionYear,
         };
       };
 
-      const actionToDispatch: SetStateAction<TestState> = {
-        type: setStateActionType,
+      const actionToDispatch: UpdateProductionYearAction = {
+        type: 'updateProductionYear',
         event: null,
-        value: { productionYear: 2010, make: 'BMW' },
+        value: 2010,
       };
 
       const reducerParameters: ControllableReducerParameters<
         TestState,
-        SetStateAction<TestState>,
+        UpdateProductionYearAction,
         { overrideProductionYear: number }
       > = {
         reducer,
@@ -318,7 +271,7 @@ describe('useControllableReducer', () => {
       }
 
       const { container } = render(<TestComponent />);
-      expect(container.firstChild).to.have.text('BMW 3 (2016)');
+      expect(container.firstChild).to.have.text('Mazda 3 (2016)');
     });
   });
 });
diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
index 049f0f454a658d..c1b7af34f33d5f 100644
--- a/packages/mui-base/src/utils/useControllableReducer.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -3,7 +3,6 @@ import {
   ActionContext,
   ControllableReducerAction,
   ControllableReducerParameters,
-  setStateActionType,
   StateChangeCallback,
   StateComparers,
 } from './useControllableReducer.types';
@@ -71,11 +70,6 @@ function useStateChangeDetection<State extends {}>(
       return;
     }
 
-    if (lastActionRef.current.type === setStateActionType) {
-      // Don't fire change events when the value has been changed externally (e.g. by changing the controlled prop).
-      return;
-    }
-
     const previousState = getControlledState(internalPreviousStateRef.current, controlledProps);
 
     (Object.keys(nextState) as (keyof State)[]).forEach((key) => {
diff --git a/packages/mui-base/src/utils/useControllableReducer.types.ts b/packages/mui-base/src/utils/useControllableReducer.types.ts
index bb6b2cb2eda76d..e1259292b1af1e 100644
--- a/packages/mui-base/src/utils/useControllableReducer.types.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.types.ts
@@ -54,14 +54,6 @@ export interface ControllableReducerParameters<
   actionAddOn?: ActionContextValue;
 }
 
-export const setStateActionType = 'controlledReducer:setState';
-
-export interface SetStateAction<State> {
-  type: typeof setStateActionType;
-  event: null;
-  value: Partial<State>;
-}
-
 /*
  * The standard shape of the action accepted by the controllable reducer
  */

From 1a05c7972697b344c1b1fa8b90c2e2e0f404a7f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 23:38:37 +0200
Subject: [PATCH 42/49] Simplify, rename and explain the action addon concept

---
 .../mui-base/src/useList/listActions.types.ts |  3 +
 packages/mui-base/src/useList/listReducer.ts  | 66 ++++++++-----------
 packages/mui-base/src/useList/useList.ts      | 61 +++++++++--------
 .../mui-base/src/useList/useList.types.ts     | 59 ++++++++++++-----
 packages/mui-base/src/useMenu/menuReducer.ts  | 11 ++--
 packages/mui-base/src/useMenu/useMenu.ts      |  2 +-
 .../src/useSelect/selectReducer.test.ts       | 15 +++--
 .../mui-base/src/useSelect/selectReducer.ts   | 17 +++--
 packages/mui-base/src/useSelect/useSelect.ts  |  2 +-
 .../src/useTabsList/tabsListReducer.ts        | 12 ++--
 .../mui-base/src/useTabsList/useTabsList.ts   |  2 +-
 .../src/utils/useControllableReducer.test.tsx |  4 +-
 .../src/utils/useControllableReducer.ts       | 34 ++++++----
 .../src/utils/useControllableReducer.types.ts | 15 +++--
 14 files changed, 175 insertions(+), 128 deletions(-)

diff --git a/packages/mui-base/src/useList/listActions.types.ts b/packages/mui-base/src/useList/listActions.types.ts
index 32c696000be93f..3c30cfd155aef8 100644
--- a/packages/mui-base/src/useList/listActions.types.ts
+++ b/packages/mui-base/src/useList/listActions.types.ts
@@ -49,6 +49,9 @@ interface ItemsChangeAction<ItemValue> {
   previousItems: ItemValue[];
 }
 
+/**
+ * A union of all standard actions that can be dispatched to the list reducer.
+ */
 export type ListAction<ItemValue> =
   | BlurAction
   | FocusAction
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index ecdb482b71cf96..8fd7ec49f6e5b2 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -1,15 +1,5 @@
-import { ActionContext } from '../utils/useControllableReducer.types';
 import { ListActionTypes } from './listActions.types';
-import {
-  ListState,
-  ListActionAddOnValue,
-  ListReducerAction,
-  ListActionAddOn,
-} from './useList.types';
-
-export type ListActionContext<ItemValue, AdditionalContext> = ActionContext<
-  ListActionAddOn<ItemValue> & AdditionalContext
->;
+import { ListState, ListReducerAction, ListActionContext } from './useList.types';
 
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
@@ -69,14 +59,14 @@ function findValidItemToHighlight<ItemValue>(
  *
  * @param previouslyHighlightedValue The item from which to start the search for the next candidate.
  * @param offset The offset from the previously highlighted item to search for the next candidate or a special named value ('reset', 'start', 'end').
- * @param listConfig The confguration of the list.
+ * @param context The list action context.
  *
  * @returns The next item to highlight or null if no item is valid.
  */
 export function moveHighlight<ItemValue>(
   previouslyHighlightedValue: ItemValue | null,
   offset: number | 'reset' | 'start' | 'end',
-  listConfig: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ) {
   const {
     items,
@@ -85,7 +75,7 @@ export function moveHighlight<ItemValue>(
     disabledItemsFocusable,
     itemComparer,
     focusManagement,
-  } = listConfig;
+  } = context;
 
   // TODO: make this configurable
   // The always should be an item highlighted when focus is managed by the DOM
@@ -221,12 +211,12 @@ export function toggleSelection<ItemValue>(
 function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
   item: ItemValue,
   state: State,
-  props: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ): State {
-  const { itemComparer = (o, v) => o === v, isItemDisabled = () => false, selectionLimit } = props;
+  const { itemComparer, isItemDisabled, selectionLimit, items } = context;
   const { selectedValues } = state;
 
-  const itemIndex = props.items.findIndex((i) => itemComparer(item, i));
+  const itemIndex = items.findIndex((i) => itemComparer(item, i));
 
   if (isItemDisabled(item, itemIndex)) {
     return state;
@@ -245,34 +235,34 @@ function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
 function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
   key: string,
   state: State,
-  parameters: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ): State {
   const previouslySelectedValue = state.highlightedValue;
-  const { orientation, pageSize } = parameters;
+  const { orientation, pageSize } = context;
 
   switch (key) {
     case 'Home':
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 'start', parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, 'start', context),
       };
 
     case 'End':
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 'end', parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, 'end', context),
       };
 
     case 'PageUp':
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, -pageSize, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, -pageSize, context),
       };
 
     case 'PageDown':
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, pageSize, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, pageSize, context),
       };
 
     case 'ArrowUp':
@@ -282,7 +272,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, -1, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, -1, context),
       };
 
     case 'ArrowDown':
@@ -292,7 +282,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, 1, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, 1, context),
       };
 
     case 'ArrowLeft': {
@@ -304,7 +294,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, offset, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, offset, context),
       };
     }
 
@@ -317,7 +307,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
       return {
         ...state,
-        highlightedValue: moveHighlight(previouslySelectedValue, offset, parameters),
+        highlightedValue: moveHighlight(previouslySelectedValue, offset, context),
       };
     }
 
@@ -327,7 +317,7 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
         return state;
       }
 
-      return handleItemSelection(state.highlightedValue, state, parameters);
+      return handleItemSelection(state.highlightedValue, state, context);
 
     default:
       break;
@@ -338,9 +328,9 @@ function handleKeyDown<ItemValue, State extends ListState<ItemValue>>(
 
 function handleBlur<ItemValue, State extends ListState<ItemValue>>(
   state: State,
-  props: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ): State {
-  if (props.focusManagement === 'DOM') {
+  if (context.focusManagement === 'DOM') {
     return state;
   }
 
@@ -368,15 +358,15 @@ function textCriteriaMatches<ItemValue>(
 function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
   state: State,
   searchString: string,
-  props: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ): State {
-  const { items, isItemDisabled, disabledItemsFocusable, itemStringifier } = props;
+  const { items, isItemDisabled, disabledItemsFocusable, itemStringifier } = context;
 
   const startWithCurrentItem = searchString.length > 1;
 
   let nextItem = startWithCurrentItem
     ? state.highlightedValue
-    : moveHighlight(state.highlightedValue, 1, props);
+    : moveHighlight(state.highlightedValue, 1, context);
 
   for (let index = 0; index < items.length; index += 1) {
     // Return un-mutated state if looped back to the currently highlighted value
@@ -395,7 +385,7 @@ function handleTextNavigation<ItemValue, State extends ListState<ItemValue>>(
       };
     }
     // Move to the next element.
-    nextItem = moveHighlight(nextItem, 1, props);
+    nextItem = moveHighlight(nextItem, 1, context);
   }
 
   // No item matches the text search criteria
@@ -406,16 +396,16 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
   items: ItemValue[],
   previousItems: ItemValue[],
   state: State,
-  props: ListActionAddOnValue<ItemValue>,
+  context: ListActionContext<ItemValue>,
 ): State {
-  const { itemComparer, focusManagement } = props;
+  const { itemComparer, focusManagement } = context;
 
   let newHighlightedValue: ItemValue | null = null;
 
   if (state.highlightedValue != null) {
     newHighlightedValue = items.find((item) => itemComparer(item, state.highlightedValue!)) ?? null;
   } else if (focusManagement === 'DOM' && previousItems.length === 0) {
-    newHighlightedValue = moveHighlight(null, 'reset', props);
+    newHighlightedValue = moveHighlight(null, 'reset', context);
   }
 
   // exclude selected values that are no longer in the items list
@@ -433,7 +423,7 @@ function handleItemsChange<ItemValue, State extends ListState<ItemValue>>(
 
 export default function listReducer<ItemValue, State extends ListState<ItemValue>>(
   state: State,
-  action: ListReducerAction<ItemValue> & { context: ListActionAddOn<ItemValue> },
+  action: ListReducerAction<ItemValue> & { context: ListActionContext<ItemValue> },
 ): State {
   const { type, context } = action;
 
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 8c2a2443e824ca..f29bdb26178bda 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -2,11 +2,10 @@ import * as React from 'react';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
 import {
   UseListParameters,
-  ListActionAddOnValue,
   ListItemState,
   UseListRootSlotProps,
   ListState,
-  ListActionAddOn,
+  ListActionContext,
 } from './useList.types';
 import { ListActionTypes, ListAction } from './listActions.types';
 import { ListContextValue } from './ListContext';
@@ -45,14 +44,19 @@ const defaultGetInitialState = () => ({
  *
  * Supports highlighting a single item and selecting an arbitrary number of items.
  *
+ * @template ItemValue The type of the item values.
+ * @template State The type of the list state. This should be a subtype of `ListState<ItemValue>`.
+ * @template CustomAction The type of the actions that can be dispatched (besides the standard ListAction).
+ * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
+ *
  * @ignore - internal hook.
  */
 function useList<
   ItemValue,
   State extends ListState<ItemValue> = ListState<ItemValue>,
   CustomAction extends ControllableReducerAction = never,
-  CustomActionAddon = {},
->(params: UseListParameters<ItemValue, State, CustomAction, CustomActionAddon>) {
+  CustomActionContext = {},
+>(params: UseListParameters<ItemValue, State, CustomAction, CustomActionContext>) {
   const {
     controlledProps = EMPTY_OBJECT,
     disabledItemsFocusable = false,
@@ -71,7 +75,7 @@ function useList<
     onHighlightChange,
     orientation = 'vertical',
     pageSize = 5,
-    reducerActionAddon: externalActionAddon = {} as CustomActionAddon,
+    reducerActionContext = EMPTY_OBJECT as CustomActionContext,
     selectionLimit = null,
     stateReducer: externalReducer,
   } = params;
@@ -79,13 +83,13 @@ function useList<
   if (process.env.NODE_ENV !== 'production') {
     if (focusManagement === 'DOM' && getItemDomElement == null) {
       throw new Error(
-        'The `getItemDomElement` prop is required when using the `DOM` focus management.',
+        'useList: The `getItemDomElement` prop is required when using the `DOM` focus management.',
       );
     }
 
     if (focusManagement === 'activeDescendant' && getItemId == null) {
       throw new Error(
-        'The `getItemId` prop is required when using the `activeDescendant` focus management.',
+        'useList: The `getItemId` prop is required when using the `activeDescendant` focus management.',
       );
     }
   }
@@ -124,6 +128,7 @@ function useList<
     [itemComparer],
   );
 
+  // This gets called whenever a reducer changes the state.
   const handleStateChange: StateChangeCallback<State> = React.useCallback(
     (event, field, value, reason, state) => {
       onStateChange?.(event, field, value, reason, state);
@@ -150,7 +155,9 @@ function useList<
     [handleHighlightChange, onChange, onStateChange],
   );
 
-  const reducerContext: ListActionAddOnValue<ItemValue> = React.useMemo(() => {
+  // The following object is added to each action when it's dispatched.
+  // It's accessible in the reducer via the `action.context` field.
+  const listActionContext: ListActionContext<ItemValue> = React.useMemo(() => {
     return {
       disabledItemsFocusable,
       disableListWrap,
@@ -181,22 +188,23 @@ function useList<
   ]);
 
   const initialState = getInitialState();
-  const reducer = externalReducer ?? defaultReducer;
+  const reducer = (externalReducer ?? defaultReducer) as React.Reducer<
+    State,
+    ListAction<ItemValue> | CustomAction
+  >;
 
-  const actionAddOn: ListActionAddOn<ItemValue> & CustomActionAddon = React.useMemo(
-    () => ({ ...externalActionAddon, ...reducerContext }),
-    [externalActionAddon, reducerContext],
+  const actionContext: ListActionContext<ItemValue> & CustomActionContext = React.useMemo(
+    () => ({ ...reducerActionContext, ...listActionContext }),
+    [reducerActionContext, listActionContext],
   );
 
-  type ListActionsWithCustomActions = CustomAction | ListAction<ItemValue>;
-
   const [state, dispatch] = useControllableReducer<
     State,
-    ListActionsWithCustomActions,
-    ListActionAddOn<ItemValue> & CustomActionAddon
+    ListAction<ItemValue> | CustomAction,
+    ListActionContext<ItemValue> & CustomActionContext
   >({
-    reducer: reducer as any,
-    actionAddOn,
+    reducer,
+    actionContext,
     initialState: initialState as State,
     controlledProps,
     stateComparers,
@@ -213,18 +221,14 @@ function useList<
     }),
   );
 
-  const highlightedIndex = React.useMemo(() => {
-    return highlightedValue == null
-      ? -1
-      : items.findIndex((item) => itemComparer(item, highlightedValue));
-  }, [highlightedValue, items, itemComparer]);
-
   // introducing refs to avoid recreating the getOptionState function on each change.
   const latestSelectedValues = useLatest(selectedValues);
-  const latestHighlightedIndex = useLatest(highlightedIndex);
+  const latestHighlightedValue = useLatest(highlightedValue);
   const previousItems = React.useRef<ItemValue[]>([]);
 
   React.useEffect(() => {
+    // Whenever the `items` object changes, we need to determine if the actual items changed.
+    // If they did, we need to dispatch an `itemsChange` action, so the selected/highlighted state is updated.
     if (areArraysEqual(previousItems.current, items, itemComparer)) {
       return;
     }
@@ -379,7 +383,9 @@ function useList<
       );
 
       const disabled = isItemDisabled(item, index);
-      const highlighted = latestHighlightedIndex.current === index && index !== -1;
+      const highlighted =
+        latestHighlightedValue.current != null &&
+        itemComparer(item, latestHighlightedValue.current);
       const focusable = isItemFocusable(item, highlighted, disabled);
 
       return {
@@ -395,7 +401,7 @@ function useList<
       isItemDisabled,
       itemComparer,
       latestSelectedValues,
-      latestHighlightedIndex,
+      latestHighlightedValue,
       isItemFocusable,
     ],
   );
@@ -413,6 +419,7 @@ function useList<
   React.useDebugValue({
     highlightedOption: highlightedValue,
     selectedOptions: selectedValues,
+    state,
   });
 
   return {
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 3a3aba450e6d41..c3dd77cf7db354 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -2,13 +2,12 @@ import * as React from 'react';
 import { Simplify } from '@mui/types';
 import { ListAction } from './listActions.types';
 import {
-  ActionContext,
+  ActionWithContext,
   ControllableReducerAction,
   StateChangeCallback,
 } from '../utils/useControllableReducer.types';
-import type { ListActionContext } from './listReducer';
 
-type ListActionAddOnValueRequiredKeys =
+type ListActionContextRequiredKeys =
   | 'disabledItemsFocusable'
   | 'disableListWrap'
   | 'focusManagement'
@@ -23,16 +22,26 @@ type ListActionAddOnValueRequiredKeys =
 /**
  * The subset of `UseListParameters` that is passed to the list reducer actions.
  */
-export type ListActionAddOnValue<ItemValue> = Simplify<
-  Required<Pick<UseListParameters<ItemValue, any, any>, ListActionAddOnValueRequiredKeys>>
+export type ListActionContext<ItemValue> = Simplify<
+  Required<Pick<UseListParameters<ItemValue, any, any>, ListActionContextRequiredKeys>>
 >;
 
-// TODO: not needed
-export type ListActionAddOn<ItemValue> = ListActionAddOnValue<ItemValue>;
-
-export type ListReducerAction<ItemValue, CustomActionAddon = {}> = ListAction<ItemValue> &
-  ListActionContext<ItemValue, CustomActionAddon>;
+/**
+ * The action object augmented with the action context ({@linkcode ListActionContext} instance).
+ * Instances of this type are passed to the reducer.
+ *
+ * @template ItemValue The type of the item values.
+ * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
+ */
+export type ListReducerAction<ItemValue, CustomActionContext = {}> = ActionWithContext<
+  ListAction<ItemValue>,
+  ListActionContext<ItemValue> & CustomActionContext
+>;
 
+/**
+ * The state of the list.
+ * Modifications to this state should be done via the reducer.
+ */
 export interface ListState<ItemValue> {
   /**
    * The item that is currently highlighted.
@@ -44,18 +53,33 @@ export interface ListState<ItemValue> {
   selectedValues: ItemValue[];
 }
 
-export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomActionAddon> = (
+/**
+ * Type of the reducer that operates on the list state.
+ *
+ * @template ItemValue The type of the item values.
+ * @template State The type of the list state. This should be a subtype of ListState<ItemValue>.
+ * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
+ */
+export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomActionContext> = (
   state: State,
-  action: ListReducerAction<ItemValue, CustomActionAddon>,
+  action: ListReducerAction<ItemValue, CustomActionContext>,
 ) => State;
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
 
+/**
+ * Parameters of the useList hook.
+ *
+ * @template ItemValue The type of the item values.
+ * @template State The type of the list state. This should be a subtype of `ListState<ItemValue>`.
+ * @template CustomAction The type of the actions that can be dispatched (besides the standard ListAction).
+ * @template CustomActionContext The shape of additional properties that will be added to actions when dispatched.
+ */
 export interface UseListParameters<
   ItemValue,
   State extends ListState<ItemValue> = ListState<ItemValue>,
   CustomAction extends ControllableReducerAction = never,
-  CustomActionAddon = {},
+  CustomActionContext = {},
 > {
   /**
    * The externally controlled values (highlighted and selected item(s)) of the list.
@@ -156,8 +180,9 @@ export interface UseListParameters<
   items: ItemValue[];
   /**
    * Additional data to be passed to all the reducer actions.
+   * It will be available in the `context` property of the action when dispatched.
    */
-  reducerActionAddon?: CustomActionAddon;
+  reducerActionContext?: CustomActionContext;
   /**
    * Orientation of the items in the list.
    * Determines the actions that are performed when arrow keys are pressed.
@@ -176,8 +201,10 @@ export interface UseListParameters<
    */
   stateReducer?: (
     state: State,
-    action: (ListAction<ItemValue> | CustomAction) &
-      ActionContext<ListActionAddOn<ItemValue> & CustomActionAddon>,
+    action: ActionWithContext<
+      ListAction<ItemValue> | CustomAction,
+      ListActionContext<ItemValue> & CustomActionContext
+    >,
   ) => State;
 }
 
diff --git a/packages/mui-base/src/useMenu/menuReducer.ts b/packages/mui-base/src/useMenu/menuReducer.ts
index 2ca8d41392bafb..9a0ac7b2406064 100644
--- a/packages/mui-base/src/useMenu/menuReducer.ts
+++ b/packages/mui-base/src/useMenu/menuReducer.ts
@@ -1,11 +1,14 @@
-import { ListAction, ListActionAddOn, ListActionTypes, listReducer } from '../useList';
-import { ActionContext } from '../utils/useControllableReducer.types';
+import { ListAction, ListActionContext, ListActionTypes, listReducer } from '../useList';
+import { ActionWithContext } from '../utils/useControllableReducer.types';
 import { MenuInternalState } from './useMenu.types';
 
+export type MenuActionContext = ListActionContext<string> & {
+  listboxRef: React.RefObject<HTMLElement>;
+};
+
 export default function menuReducer(
   state: MenuInternalState,
-  action: ListAction<string> &
-    ActionContext<ListActionAddOn<string> & { listboxRef: React.RefObject<HTMLElement> }>,
+  action: ActionWithContext<ListAction<string>, MenuActionContext>,
 ) {
   if (action.type === ListActionTypes.itemHover) {
     return state;
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 7f8e22689f9a22..5a5f033a08fd8c 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -84,7 +84,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
       subitems.get(id)?.label || subitems.get(id)?.ref.current?.innerText,
     listRef: handleRef,
     onStateChange: stateChangeHandler,
-    reducerActionAddon: { listboxRef },
+    reducerActionContext: { listboxRef },
     selectionLimit: 0,
     stateReducer: menuReducer,
   });
diff --git a/packages/mui-base/src/useSelect/selectReducer.test.ts b/packages/mui-base/src/useSelect/selectReducer.test.ts
index 7d1a39e7598c6e..c02b876cebeaed 100644
--- a/packages/mui-base/src/useSelect/selectReducer.test.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.test.ts
@@ -1,6 +1,7 @@
 import { expect } from 'chai';
 import selectReducer, { SelectActionContext } from './selectReducer';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
+import { ActionWithContext } from '../utils/useControllableReducer.types';
 
 describe('selectReducer', () => {
   const irrelevantConfig = {
@@ -24,7 +25,7 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & SelectActionContext<unknown> = {
+      const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
@@ -44,7 +45,7 @@ describe('selectReducer', () => {
         open: true,
       };
 
-      const action: SelectAction & SelectActionContext<unknown> = {
+      const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
@@ -64,7 +65,7 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & SelectActionContext<string> = {
+      const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
@@ -85,7 +86,7 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: SelectAction & SelectActionContext<string> = {
+      const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
@@ -113,7 +114,7 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & SelectActionContext<unknown> = {
+          const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
@@ -134,7 +135,7 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & SelectActionContext<string> = {
+          const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
@@ -156,7 +157,7 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: SelectAction & SelectActionContext<string> = {
+          const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
diff --git a/packages/mui-base/src/useSelect/selectReducer.ts b/packages/mui-base/src/useSelect/selectReducer.ts
index 3aa3202ebe4275..9ca118ea1d1496 100644
--- a/packages/mui-base/src/useSelect/selectReducer.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.ts
@@ -1,20 +1,23 @@
 import {
   ListAction,
-  ListActionAddOn,
+  ListActionContext,
   moveHighlight,
   listReducer,
   ListActionTypes,
 } from '../useList';
-import { ActionContext } from '../utils/useControllableReducer.types';
+import { ActionWithContext } from '../utils/useControllableReducer.types';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
 
-export type SelectActionContext<OptionValue> = ActionContext<
-  ListActionAddOn<OptionValue> & { multiple: boolean }
->;
+export type SelectActionContext<OptionValue> = ListActionContext<OptionValue> & {
+  multiple: boolean;
+};
 
 export default function selectReducer<OptionValue>(
   state: SelectInternalState<OptionValue>,
-  action: (ListAction<OptionValue> | SelectAction) & SelectActionContext<OptionValue>,
+  action: ActionWithContext<
+    ListAction<OptionValue> | SelectAction,
+    SelectActionContext<OptionValue>
+  >,
 ) {
   const { open } = state;
   const {
@@ -64,7 +67,7 @@ export default function selectReducer<OptionValue>(
 
   const newState: SelectInternalState<OptionValue> = listReducer(
     state,
-    action as ListAction<OptionValue> & SelectActionContext<OptionValue>,
+    action as ActionWithContext<ListAction<OptionValue>, SelectActionContext<OptionValue>>,
   );
 
   switch (action.type) {
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 4706c72f7190b9..a54f6a50571025 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -192,7 +192,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
         }
       }
     },
-    reducerActionAddon: React.useMemo(() => ({ multiple }), [multiple]),
+    reducerActionContext: React.useMemo(() => ({ multiple }), [multiple]),
     items: optionValues,
     itemStringifier: stringifyOption,
     selectionLimit: multiple ? null : 1,
diff --git a/packages/mui-base/src/useTabsList/tabsListReducer.ts b/packages/mui-base/src/useTabsList/tabsListReducer.ts
index 75e9905493b245..019f2611be1ade 100644
--- a/packages/mui-base/src/useTabsList/tabsListReducer.ts
+++ b/packages/mui-base/src/useTabsList/tabsListReducer.ts
@@ -1,14 +1,14 @@
-import { ListState, ListAction, ListActionAddOn, listReducer, ListActionTypes } from '../useList';
-import { ActionContext } from '../utils/useControllableReducer.types';
+import { ListState, ListAction, ListActionContext, listReducer, ListActionTypes } from '../useList';
+import { ActionWithContext } from '../utils/useControllableReducer.types';
 import { TabsListActionTypes, ValueChangeAction } from './useTabsList.types';
 
-export type TabsListActionContext = ActionContext<
-  ListActionAddOn<string | number> & { selectionFollowsFocus: boolean }
->;
+export type TabsListActionContext = ListActionContext<string | number> & {
+  selectionFollowsFocus: boolean;
+};
 
 export default function tabsListReducer(
   state: ListState<string | number>,
-  action: (ListAction<string | number> | ValueChangeAction) & TabsListActionContext,
+  action: ActionWithContext<ListAction<string | number> | ValueChangeAction, TabsListActionContext>,
 ) {
   if (action.type === TabsListActionTypes.valueChange) {
     return {
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index d419a407f8c9f1..54aa5d73b1386d 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -119,7 +119,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     listRef: externalRef,
     onChange: handleChange,
     orientation: listOrientation,
-    reducerActionAddon: React.useMemo(
+    reducerActionContext: React.useMemo(
       () => ({ selectionFollowsFocus: selectionFollowsFocus || false }),
       [selectionFollowsFocus],
     ),
diff --git a/packages/mui-base/src/utils/useControllableReducer.test.tsx b/packages/mui-base/src/utils/useControllableReducer.test.tsx
index f00a47fa6988fe..812e9b81b50958 100644
--- a/packages/mui-base/src/utils/useControllableReducer.test.tsx
+++ b/packages/mui-base/src/utils/useControllableReducer.test.tsx
@@ -231,7 +231,7 @@ describe('useControllableReducer', () => {
     });
   });
 
-  describe('param: actionAddOn', () => {
+  describe('param: actionContext', () => {
     it('augments actions with the object provided to the reducer', () => {
       const reducer = (
         state: TestState,
@@ -257,7 +257,7 @@ describe('useControllableReducer', () => {
         reducer,
         controlledProps: {},
         initialState: { make: 'Mazda', model: '3', productionYear: 2022 },
-        actionAddOn: { overrideProductionYear: 2016 },
+        actionContext: { overrideProductionYear: 2016 },
       };
 
       function TestComponent() {
diff --git a/packages/mui-base/src/utils/useControllableReducer.ts b/packages/mui-base/src/utils/useControllableReducer.ts
index c1b7af34f33d5f..f5d5dfee473482 100644
--- a/packages/mui-base/src/utils/useControllableReducer.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.ts
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import {
-  ActionContext,
+  ActionWithContext,
   ControllableReducerAction,
   ControllableReducerParameters,
   StateChangeCallback,
@@ -56,6 +56,11 @@ interface UseStateChangeDetectionParameters<State extends {}> {
   lastActionRef: React.MutableRefObject<ControllableReducerAction | null>;
 }
 
+/**
+ * Defines an effect that compares the next state with the previous state and calls
+ * the `onStateChange` callback if the state has changed.
+ * The comparison is done based on the `stateComparers` parameter.
+ */
 function useStateChangeDetection<State extends {}>(
   parameters: UseStateChangeDetectionParameters<State>,
 ) {
@@ -117,16 +122,21 @@ function useStateChangeDetection<State extends {}>(
  * If a state item has a corresponding comparer, it will be used to determine if the state has changed.
  * This is useful when the state item is an object and you want to compare only a subset of its properties or if it's an array and you want to compare its contents.
  *
- * An additional feature is the `actionAddOn` parameter. It allows you to add additional properties to every action object.
+ * An additional feature is the `actionContext` parameter. It allows you to add additional properties to every action object,
+ * similarly to how React context is implicitly available to every component.
+ *
+ * @template State - The type of the state calculated by the reducer.
+ * @template Action - The type of the actions that can be dispatched.
+ * @template ActionContext - The type of the additional properties that will be added to every action object.
  *
  * @ignore - internal hook.
  */
 export default function useControllableReducer<
   State extends {},
   Action extends ControllableReducerAction,
-  ActionContextValue = undefined,
+  ActionContext = undefined,
 >(
-  parameters: ControllableReducerParameters<State, Action, ActionContextValue>,
+  parameters: ControllableReducerParameters<State, Action, ActionContext>,
 ): [State, (action: Action) => void] {
   const lastActionRef = React.useRef<Action | null>(null);
 
@@ -136,12 +146,12 @@ export default function useControllableReducer<
     controlledProps = EMPTY_OBJECT,
     stateComparers = EMPTY_OBJECT,
     onStateChange = NOOP,
-    actionAddOn,
+    actionContext,
   } = parameters;
 
   // The reducer that is passed to React.useReducer is wrapped with a function that augments the state with controlled values.
   const reducerWithControlledState = React.useCallback(
-    (state: State, action: Action & ActionContext<ActionContextValue>) => {
+    (state: State, action: ActionWithContext<Action, ActionContext>) => {
       lastActionRef.current = action;
       const controlledState = getControlledState(state, controlledProps);
       return reducer(controlledState, action);
@@ -151,15 +161,15 @@ export default function useControllableReducer<
 
   const [nextState, dispatch] = React.useReducer(reducerWithControlledState, initialState);
 
-  // The action that is passed to dispatch is augmented with the actionAddOn.
-  const dispatchWithAddOn = React.useCallback(
+  // The action that is passed to dispatch is augmented with the actionContext.
+  const dispatchWithContext = React.useCallback(
     (action: Action) => {
       dispatch({
         ...action,
-        context: actionAddOn,
-      } as Action & ActionContext<ActionContextValue>);
+        context: actionContext,
+      } as ActionWithContext<Action, ActionContext>);
     },
-    [actionAddOn],
+    [actionContext],
   );
 
   useStateChangeDetection<State>({
@@ -171,5 +181,5 @@ export default function useControllableReducer<
     lastActionRef,
   });
 
-  return [getControlledState(nextState, controlledProps), dispatchWithAddOn];
+  return [getControlledState(nextState, controlledProps), dispatchWithContext];
 }
diff --git a/packages/mui-base/src/utils/useControllableReducer.types.ts b/packages/mui-base/src/utils/useControllableReducer.types.ts
index e1259292b1af1e..c4769af6c32ae9 100644
--- a/packages/mui-base/src/utils/useControllableReducer.types.ts
+++ b/packages/mui-base/src/utils/useControllableReducer.types.ts
@@ -1,3 +1,6 @@
+/**
+ * Functions that compare fields of a given State object
+ */
 export type StateComparers<State> = {
   [key in keyof State]?: (value1: State[key], value2: State[key]) => boolean;
 };
@@ -10,8 +13,8 @@ export type StateChangeCallback<State> = <StateKey extends keyof State>(
   state: State,
 ) => void;
 
-export type ActionContext<Value> = {
-  context: Value;
+export type ActionWithContext<Action, ContextValue> = Action & {
+  context: ContextValue;
 };
 
 /**
@@ -20,16 +23,16 @@ export type ActionContext<Value> = {
 export interface ControllableReducerParameters<
   State,
   Action extends ControllableReducerAction,
-  ActionContextValue = undefined,
+  ActionContext = undefined,
 > {
   /**
    * The reducer function.
    *
    * @param state The previous state. If controlledProps are defined, the state will contain the values of the controlledProps.
-   * @param action The action to dispatch. The action can be augmented with the `actionAddOn`.
+   * @param action The action to dispatch. The action can be augmented with the `actionContext`.
    * @returns The updated state.
    */
-  reducer: (state: State, action: Action & ActionContext<ActionContextValue>) => State;
+  reducer: (state: State, action: ActionWithContext<Action, ActionContext>) => State;
   /**
    * The controlled props that will override the state items.
    */
@@ -51,7 +54,7 @@ export interface ControllableReducerParameters<
   /**
    * Additional properties that will be added to the action.
    */
-  actionAddOn?: ActionContextValue;
+  actionContext?: ActionContext;
 }
 
 /*

From f7448ade690c74cf3799211092d7dd6b33ae3109 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Fri, 7 Apr 2023 23:44:52 +0200
Subject: [PATCH 43/49] Remove redundant return values from useList

---
 packages/mui-base/src/useList/useList.ts        |  4 ----
 packages/mui-base/src/useMenu/useMenu.ts        | 17 ++++++++---------
 packages/mui-base/src/useMenu/useMenu.types.ts  |  2 +-
 packages/mui-base/src/useSelect/useSelect.ts    |  4 +---
 .../mui-base/src/useTabsList/useTabsList.ts     |  7 +++----
 5 files changed, 13 insertions(+), 21 deletions(-)

diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index f29bdb26178bda..78a8c22e95f6d0 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -417,8 +417,6 @@ function useList<
   );
 
   React.useDebugValue({
-    highlightedOption: highlightedValue,
-    selectedOptions: selectedValues,
     state,
   });
 
@@ -426,8 +424,6 @@ function useList<
     contextValue,
     dispatch,
     getRootProps,
-    highlightedOption: highlightedValue,
-    selectedOptions: selectedValues,
     state,
   };
 }
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 5a5f033a08fd8c..05514292f06005 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -65,9 +65,8 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
   const {
     dispatch,
     getRootProps,
-    highlightedOption,
     contextValue: listContextValue,
-    state: { open },
+    state: { open, highlightedValue },
   } = useList({
     controlledProps,
     disabledItemsFocusable: true,
@@ -90,17 +89,17 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
   });
 
   React.useEffect(() => {
-    if (open && highlightedOption === subitemKeys[0]) {
+    if (open && highlightedValue === subitemKeys[0]) {
       subitems.get(subitemKeys[0])?.ref?.current?.focus();
     }
-  }, [open, highlightedOption, subitems, subitemKeys]);
+  }, [open, highlightedValue, subitems, subitemKeys]);
 
   React.useEffect(() => {
     // set focus to the highlighted item (but prevent stealing focus from other elements on the page)
-    if (listboxRef.current?.contains(document.activeElement) && highlightedOption !== null) {
-      subitems?.get(highlightedOption)?.ref.current?.focus();
+    if (listboxRef.current?.contains(document.activeElement) && highlightedValue !== null) {
+      subitems?.get(highlightedValue)?.ref.current?.focus();
     }
-  }, [highlightedOption, subitems]);
+  }, [highlightedValue, subitems]);
 
   const getListboxProps = <TOther extends EventHandlers>(
     otherHandlers: TOther = {} as TOther,
@@ -113,7 +112,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     };
   };
 
-  React.useDebugValue({ subitems, highlightedOption });
+  React.useDebugValue({ subitems, highlightedValue });
 
   return {
     contextValue: {
@@ -122,7 +121,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     },
     dispatch,
     getListboxProps,
-    highlightedOption,
+    highlightedValue,
     menuItems: subitems,
     open,
   };
diff --git a/packages/mui-base/src/useMenu/useMenu.types.ts b/packages/mui-base/src/useMenu/useMenu.types.ts
index 586280beb21111..219631da5b6bdc 100644
--- a/packages/mui-base/src/useMenu/useMenu.types.ts
+++ b/packages/mui-base/src/useMenu/useMenu.types.ts
@@ -50,7 +50,7 @@ export interface UseMenuReturnValue {
   /**
    * The highlighted option in the menu listbox.
    */
-  highlightedOption: string | null;
+  highlightedValue: string | null;
   /**
    * Items in the menu listbox.
    */
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index a54f6a50571025..f095005ec8a1f7 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -202,10 +202,8 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
   const {
     dispatch,
     getRootProps: getListboxRootProps,
-    highlightedOption,
-    selectedOptions,
     contextValue: listContextValue,
-    state: { open },
+    state: { open, highlightedValue: highlightedOption, selectedValues: selectedOptions },
   } = useList(useListParameters);
 
   React.useEffect(() => {
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 54aa5d73b1386d..34457a9d8b20f5 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -102,8 +102,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     contextValue: listContextValue,
     dispatch,
     getRootProps: getListboxRootProps,
-    highlightedOption,
-    selectedOptions,
+    state: { highlightedValue, selectedValues },
   } = useList<
     string | number,
     ListState<string | number>,
@@ -156,8 +155,8 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
     dispatch,
     isRtl,
     orientation,
-    selectedValue: selectedOptions[0] ?? null,
-    highlightedValue: highlightedOption,
+    selectedValue: selectedValues[0] ?? null,
+    highlightedValue,
     getRootProps,
     contextValue: {
       ...compoundComponentContextValue,

From b9e76dd5a624b3cfc56efe40430f0650d7dac924 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Sat, 8 Apr 2023 00:06:35 +0200
Subject: [PATCH 44/49] Add comments in useList

---
 packages/mui-base/src/useList/useList.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 78a8c22e95f6d0..2756e5340c1d4b 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -44,6 +44,12 @@ const defaultGetInitialState = () => ({
  *
  * Supports highlighting a single item and selecting an arbitrary number of items.
  *
+ * The state of the list is managed by a controllable reducer - that is a reducer that can have its state
+ * controlled from outside.
+ *
+ * By default, the state consists of `selectedValues` and `highlightedValue` but can be extended by the caller of the hook.
+ * Also the actions that can be dispatched and the reducer function can be defined externally.
+ *
  * @template ItemValue The type of the item values.
  * @template State The type of the list state. This should be a subtype of `ListState<ItemValue>`.
  * @template CustomAction The type of the actions that can be dispatched (besides the standard ListAction).
@@ -221,7 +227,7 @@ function useList<
     }),
   );
 
-  // introducing refs to avoid recreating the getOptionState function on each change.
+  // introducing refs to avoid recreating the getItemState function on each change.
   const latestSelectedValues = useLatest(selectedValues);
   const latestHighlightedValue = useLatest(highlightedValue);
   const previousItems = React.useRef<ItemValue[]>([]);
@@ -243,6 +249,10 @@ function useList<
     previousItems.current = items;
   }, [items, itemComparer, dispatch]);
 
+  // Subitems are notified of changes to the highlighted and selected values.
+  // This is not done via context because we don't want to trigger a re-render of all the subitems each time any of them changes state.
+  // Instead, we use a custom message bus to publish messages about changes.
+  // On the child component, we use a custom hook to subscribe to these messages and re-render only when the value they care about changes.
   const {
     notifySelectionChanged,
     notifyHighlightChanged,

From a4227d4263bf53275baff8b1cda009bab3add380 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 11 Apr 2023 11:07:04 +0200
Subject: [PATCH 45/49] Fix unnecessary rerendering of options

---
 docs/pages/experiments/base/listbox.tsx       | 14 ++--
 .../OptionUnstyled/OptionUnstyled.test.tsx    |  2 +-
 .../SelectUnstyled/SelectUnstyled.test.tsx    | 66 ++++++++++++++++-
 packages/mui-base/src/useList/useList.ts      | 48 +------------
 .../mui-base/src/useList/useList.types.ts     |  5 +-
 packages/mui-base/src/useList/useListItem.ts  |  4 +-
 packages/mui-base/src/useSelect/useSelect.ts  | 72 ++++++++++++++-----
 .../src/useTabsList/tabsListReducer.ts        | 21 ++++--
 8 files changed, 150 insertions(+), 82 deletions(-)

diff --git a/docs/pages/experiments/base/listbox.tsx b/docs/pages/experiments/base/listbox.tsx
index 349c4bb1a0b8c5..5f6a5c31a7f9ca 100644
--- a/docs/pages/experiments/base/listbox.tsx
+++ b/docs/pages/experiments/base/listbox.tsx
@@ -133,14 +133,18 @@ function List() {
   const itemRefs = React.useRef(new Map<number, HTMLElement>());
   const listbox = useList({
     items,
-    getItemDomElement: (item) => itemRefs.current.get(item) || null,
-    getItemId: (item) => `item-${item}`,
+    getItemDomElement: React.useCallback((item: number) => itemRefs.current.get(item) || null, []),
+    getItemId: React.useCallback((item: number) => `item-${item}`, []),
     orientation,
     focusManagement,
     selectionLimit: 1,
   });
 
-  const { getRootProps, contextValue, selectedOptions, highlightedOption } = listbox;
+  const {
+    getRootProps,
+    contextValue,
+    state: { selectedValues, highlightedValue },
+  } = listbox;
 
   const handleItemRef = React.useCallback((item: number, node: HTMLElement | null) => {
     if (node) {
@@ -196,8 +200,8 @@ function List() {
         </div>
       </div>
       <div className="state">
-        <pre>Selected: {selectedOptions.join(', ')}</pre>
-        <pre>Highlighted: {highlightedOption ?? '(none)'}</pre>
+        <pre>Selected: {selectedValues.join(', ')}</pre>
+        <pre>Highlighted: {highlightedValue ?? '(none)'}</pre>
       </div>
       <div {...getRootProps()} className="list" style={{ flexDirection }}>
         <ListContext.Provider value={contextValue}>
diff --git a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
index 1005a4af10ceb4..514f02f8b6b2a6 100644
--- a/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
+++ b/packages/mui-base/src/OptionUnstyled/OptionUnstyled.test.tsx
@@ -8,7 +8,7 @@ const dummyGetItemState = () => ({
   highlighted: false,
   selected: false,
   index: 0,
-  focusable: undefined,
+  focusable: false,
 });
 
 describe('<OptionUnstyled />', () => {
diff --git a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
index d1970880d45680..2b1e5ffba258de 100644
--- a/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
+++ b/packages/mui-base/src/SelectUnstyled/SelectUnstyled.test.tsx
@@ -5,7 +5,7 @@ import SelectUnstyled, {
   SelectUnstyledListboxSlotProps,
   selectUnstyledClasses,
 } from '@mui/base/SelectUnstyled';
-import { SelectOption } from '@mui/base/useOption';
+import useOption, { SelectOption } from '@mui/base/useOption';
 import OptionUnstyled, {
   OptionUnstyledProps,
   optionUnstyledClasses,
@@ -1002,4 +1002,68 @@ describe('<SelectUnstyled />', () => {
 
     expect(selectButton).to.have.text('1, 2');
   });
+
+  it('perf: does not rerender options unnecessarily', () => {
+    const renderOption1Spy = spy();
+    const renderOption2Spy = spy();
+    const renderOption3Spy = spy();
+    const renderOption4Spy = spy();
+
+    function Option(props: OptionUnstyledProps<number> & { renderSpy?: () => void }) {
+      const { renderSpy, value } = props;
+      renderSpy?.();
+
+      const { getRootProps } = useOption({
+        value,
+        label: value.toString(),
+        disabled: false,
+      });
+
+      return <li {...getRootProps} />;
+    }
+
+    const { getByRole } = render(
+      <SelectUnstyled>
+        <Option renderSpy={renderOption1Spy} value={1}>
+          1
+        </Option>
+        <Option renderSpy={renderOption2Spy} value={2}>
+          2
+        </Option>
+        <Option renderSpy={renderOption3Spy} value={3}>
+          3
+        </Option>
+        <Option renderSpy={renderOption4Spy} value={4}>
+          4
+        </Option>
+      </SelectUnstyled>,
+    );
+
+    renderOption1Spy.resetHistory();
+    renderOption2Spy.resetHistory();
+    renderOption3Spy.resetHistory();
+    renderOption4Spy.resetHistory();
+
+    const select = getByRole('combobox');
+    act(() => {
+      select.click(); // opens and highlights '1'
+    });
+
+    // React renders twice in strict mode, so we expect twice the number of spy calls
+    expect(renderOption1Spy.callCount).to.equal(2);
+
+    const listbox = getByRole('listbox');
+    fireEvent.keyDown(listbox, { key: 'ArrowDown' }); // highlights '2'
+    expect(renderOption1Spy.callCount).to.equal(4); // '1' rerenders as it loses highlight
+    expect(renderOption2Spy.callCount).to.equal(2); // '2' rerenders as it receives highlight
+
+    fireEvent.keyDown(listbox, { key: 'Enter' }); // selects '2'
+    expect(renderOption1Spy.callCount).to.equal(4);
+    expect(renderOption2Spy.callCount).to.equal(4);
+
+    // neither the highlighted nor the selected state of these options changed,
+    // so they don't need to rerender:
+    expect(renderOption3Spy.callCount).to.equal(0);
+    expect(renderOption4Spy.callCount).to.equal(0);
+  });
 });
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 2756e5340c1d4b..34a39538d7cfe0 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -341,50 +341,6 @@ function useList<
     };
   };
 
-  const firstFocusableItem = React.useMemo(() => {
-    if (focusManagement === 'activeDescendant') {
-      // items are not focusable when using activeDescendant
-      return undefined;
-    }
-
-    if (disabledItemsFocusable) {
-      return items[0];
-    }
-
-    for (let i = 0; i < items.length; i += 1) {
-      const item = items[i];
-      if (!isItemDisabled(item, i)) {
-        return item;
-      }
-    }
-
-    return undefined;
-  }, [items, disabledItemsFocusable, focusManagement, isItemDisabled]);
-
-  const isItemFocusable = React.useCallback(
-    (item: ItemValue, highlighted: boolean, disabled: boolean) => {
-      if (focusManagement === 'activeDescendant') {
-        return undefined;
-      }
-
-      // TODO: check if using highlightedValue instead of latestHighlightedValue.current does not kill performance
-      if (highlightedValue == null) {
-        return item === firstFocusableItem;
-      }
-
-      if (!highlighted) {
-        return false;
-      }
-
-      if (disabled && !disabledItemsFocusable) {
-        return false;
-      }
-
-      return true;
-    },
-    [focusManagement, disabledItemsFocusable, firstFocusableItem, highlightedValue],
-  );
-
   const getItemState = React.useCallback(
     (item: ItemValue): ListItemState => {
       const index = items.findIndex((i) => itemComparer(i, item));
@@ -396,7 +352,7 @@ function useList<
       const highlighted =
         latestHighlightedValue.current != null &&
         itemComparer(item, latestHighlightedValue.current);
-      const focusable = isItemFocusable(item, highlighted, disabled);
+      const focusable = focusManagement === 'DOM';
 
       return {
         disabled,
@@ -412,7 +368,7 @@ function useList<
       itemComparer,
       latestSelectedValues,
       latestHighlightedValue,
-      isItemFocusable,
+      focusManagement,
     ],
   );
 
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index c3dd77cf7db354..3f004a6a1810ad 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -214,10 +214,9 @@ export interface ListItemState {
    */
   disabled: boolean;
   /**
-   * Determines if the item is focusable.
-   * If `undefined`, focusing doesn't apply as focusManagement is set to 'activeDescendant'.
+   * Determines if the item is focusable (its focus is managed by the DOM).
    */
-  focusable: boolean | undefined;
+  focusable: boolean;
   /**
    * If `true` the item is highlighted.
    */
diff --git a/packages/mui-base/src/useList/useListItem.ts b/packages/mui-base/src/useList/useListItem.ts
index 68c08de242e57a..dbd7f1acf24ad0 100644
--- a/packages/mui-base/src/useList/useListItem.ts
+++ b/packages/mui-base/src/useList/useListItem.ts
@@ -98,8 +98,8 @@ export default function useListItem<ItemValue>(
   );
 
   let tabIndex: number | undefined;
-  if (focusable !== undefined) {
-    tabIndex = focusable ? 0 : -1;
+  if (focusable) {
+    tabIndex = highlighted ? 0 : -1;
   }
 
   const getRootProps = <TOther extends EventHandlers = {}>(
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index f095005ec8a1f7..213002c61a8193 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -159,6 +159,55 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     [value, openProp],
   );
 
+  const getItemId = React.useCallback(
+    (itemValue: OptionValue) => options.get(itemValue)?.id,
+    [options],
+  );
+
+  const handleSelectionChange = React.useCallback(
+    (
+      event:
+        | React.MouseEvent<Element, MouseEvent>
+        | React.KeyboardEvent<Element>
+        | React.FocusEvent<Element, Element>
+        | null,
+      newValues: OptionValue[],
+    ) => {
+      if (multiple) {
+        onChange?.(event, newValues as SelectValue<OptionValue, Multiple>);
+      } else {
+        onChange?.(event, (newValues[0] ?? null) as SelectValue<OptionValue, Multiple>);
+      }
+    },
+    [multiple, onChange],
+  );
+
+  const handleHighlightChange = React.useCallback(
+    (
+      event:
+        | React.MouseEvent<Element, MouseEvent>
+        | React.KeyboardEvent<Element>
+        | React.FocusEvent<Element, Element>
+        | null,
+      newValue: OptionValue | null,
+    ) => {
+      onHighlightChange?.(event, newValue ?? null);
+    },
+    [onHighlightChange],
+  );
+
+  const handleStateChange = React.useCallback(
+    (e: React.SyntheticEvent | null, field: string, fieldValue: any) => {
+      if (field === 'open') {
+        onOpenChange?.(fieldValue as boolean);
+        if (fieldValue === false && e?.type !== 'blur') {
+          buttonRef.current?.focus();
+        }
+      }
+    },
+    [onOpenChange],
+  );
+
   const useListParameters: UseListParameters<
     OptionValue,
     SelectInternalState<OptionValue>,
@@ -170,28 +219,13 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
       selectedValues: defaultValue ?? [],
       open: defaultOpen,
     }),
-    getItemId: (itemValue) => options.get(itemValue)?.id,
+    getItemId,
     controlledProps: controlledState,
     isItemDisabled,
     listRef: handleListboxRef,
-    onChange: (e, newValues) => {
-      if (multiple) {
-        onChange?.(e, newValues as SelectValue<OptionValue, Multiple>);
-      } else {
-        onChange?.(e, (newValues[0] ?? null) as SelectValue<OptionValue, Multiple>);
-      }
-    },
-    onHighlightChange: (e, newValue) => {
-      onHighlightChange?.(e, newValue ?? null);
-    },
-    onStateChange: (e, field, fieldValue) => {
-      if (field === 'open') {
-        onOpenChange?.(fieldValue as boolean);
-        if (fieldValue === false && e?.type !== 'blur') {
-          buttonRef.current?.focus();
-        }
-      }
-    },
+    onChange: handleSelectionChange,
+    onHighlightChange: handleHighlightChange,
+    onStateChange: handleStateChange,
     reducerActionContext: React.useMemo(() => ({ multiple }), [multiple]),
     items: optionValues,
     itemStringifier: stringifyOption,
diff --git a/packages/mui-base/src/useTabsList/tabsListReducer.ts b/packages/mui-base/src/useTabsList/tabsListReducer.ts
index 019f2611be1ade..79c4eb6339e2bb 100644
--- a/packages/mui-base/src/useTabsList/tabsListReducer.ts
+++ b/packages/mui-base/src/useTabsList/tabsListReducer.ts
@@ -1,4 +1,11 @@
-import { ListState, ListAction, ListActionContext, listReducer, ListActionTypes } from '../useList';
+import {
+  ListState,
+  ListAction,
+  ListActionContext,
+  listReducer,
+  ListActionTypes,
+  moveHighlight,
+} from '../useList';
 import { ActionWithContext } from '../utils/useControllableReducer.types';
 import { TabsListActionTypes, ValueChangeAction } from './useTabsList.types';
 
@@ -24,10 +31,14 @@ export default function tabsListReducer(
   } = action;
 
   if (action.type === ListActionTypes.itemsChange) {
-    return {
-      ...newState,
-      highlightedValue: newState.selectedValues[0] ?? null,
-    };
+    if (newState.selectedValues.length > 0) {
+      return {
+        ...newState,
+        highlightedValue: newState.selectedValues[0],
+      };
+    }
+
+    moveHighlight(null, 'reset', action.context);
   }
 
   if (selectionFollowsFocus && newState.highlightedValue != null) {

From b074464d7b3b036bda89f50053ea0fba2b8828ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 11 Apr 2023 11:44:42 +0200
Subject: [PATCH 46/49] Finx linter violation

---
 packages/mui-joy/src/Option/Option.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/mui-joy/src/Option/Option.tsx b/packages/mui-joy/src/Option/Option.tsx
index 7bd2128cdb2b0b..a43a8a854dbaef 100644
--- a/packages/mui-joy/src/Option/Option.tsx
+++ b/packages/mui-joy/src/Option/Option.tsx
@@ -2,8 +2,8 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import composeClasses from '@mui/base/composeClasses';
 import useOption from '@mui/base/useOption';
-import useSlot from '../utils/useSlot';
 import { unstable_useForkRef as useForkRef } from '@mui/utils';
+import useSlot from '../utils/useSlot';
 import { StyledListItemButton } from '../ListItemButton/ListItemButton';
 import { styled, useThemeProps } from '../styles';
 import { useColorInversion } from '../styles/ColorInversion';

From 430ccad06ad6d9de30da00627297d8112a824932 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 11 Apr 2023 11:51:33 +0200
Subject: [PATCH 47/49] Change MD3 tabs to use null instead of false

---
 packages/mui-material-next/src/Tabs/Tabs.js      | 2 +-
 packages/mui-material-next/src/Tabs/Tabs.test.js | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/mui-material-next/src/Tabs/Tabs.js b/packages/mui-material-next/src/Tabs/Tabs.js
index d3b6ee7726b664..9dcca65a0d32a2 100644
--- a/packages/mui-material-next/src/Tabs/Tabs.js
+++ b/packages/mui-material-next/src/Tabs/Tabs.js
@@ -280,7 +280,7 @@ const Tabs = React.forwardRef(function Tabs(inProps, ref) {
     }
 
     let tabMeta;
-    if (tabsNode && value !== false) {
+    if (tabsNode && value !== null) {
       const currentChildren = tabListRef.current.children;
 
       if (currentChildren.length > 0) {
diff --git a/packages/mui-material-next/src/Tabs/Tabs.test.js b/packages/mui-material-next/src/Tabs/Tabs.test.js
index b666c4556df2f4..9d17ac411e1107 100644
--- a/packages/mui-material-next/src/Tabs/Tabs.test.js
+++ b/packages/mui-material-next/src/Tabs/Tabs.test.js
@@ -195,9 +195,9 @@ describe('<Tabs />', () => {
     });
 
     describe('indicator', () => {
-      it('should accept a false value', () => {
+      it('should accept a null value', () => {
         const { container } = render(
-          <Tabs value={false}>
+          <Tabs value={null}>
             <Tab />
             <Tab />
           </Tabs>,
@@ -1289,7 +1289,7 @@ describe('<Tabs />', () => {
 
     it('should allow to focus first tab when there are no active tabs', () => {
       const { getAllByRole } = render(
-        <Tabs value={false}>
+        <Tabs value={null}>
           <Tab />
           <Tab />
         </Tabs>,

From bba8c16577328fb107a2c6f83fe2811c48962f9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 11 Apr 2023 11:51:40 +0200
Subject: [PATCH 48/49] Docs

---
 docs/pages/base/api/use-menu.json                          | 6 +++---
 docs/pages/base/api/use-select.json                        | 4 ++--
 docs/pages/base/api/use-tabs-list.json                     | 7 +++++++
 docs/translations/api-docs/use-menu/use-menu.json          | 2 +-
 .../translations/api-docs/use-tabs-list/use-tabs-list.json | 1 +
 5 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/pages/base/api/use-menu.json b/docs/pages/base/api/use-menu.json
index 59c8e6213c3a0b..4cd0ede5cff5c2 100644
--- a/docs/pages/base/api/use-menu.json
+++ b/docs/pages/base/api/use-menu.json
@@ -17,8 +17,8 @@
     },
     "dispatch": {
       "type": {
-        "name": "(action: ListAction&lt;string, MenuInternalState&gt;) =&gt; void",
-        "description": "(action: ListAction&lt;string, MenuInternalState&gt;) =&gt; void"
+        "name": "(action: ListAction&lt;string&gt;) =&gt; void",
+        "description": "(action: ListAction&lt;string&gt;) =&gt; void"
       },
       "required": true
     },
@@ -29,7 +29,7 @@
       },
       "required": true
     },
-    "highlightedOption": {
+    "highlightedValue": {
       "type": { "name": "string | null", "description": "string | null" },
       "required": true
     },
diff --git a/docs/pages/base/api/use-select.json b/docs/pages/base/api/use-select.json
index 51d3b997a6315c..6e26cd8fc6d182 100644
--- a/docs/pages/base/api/use-select.json
+++ b/docs/pages/base/api/use-select.json
@@ -16,8 +16,8 @@
     "disabled": { "type": { "name": "boolean", "description": "boolean" }, "required": true },
     "dispatch": {
       "type": {
-        "name": "(action: ListAction&lt;Value, SelectInternalState&lt;Value&gt;&gt; | SelectAction) =&gt; void",
-        "description": "(action: ListAction&lt;Value, SelectInternalState&lt;Value&gt;&gt; | SelectAction) =&gt; void"
+        "name": "(action: ListAction&lt;Value&gt; | SelectAction) =&gt; void",
+        "description": "(action: ListAction&lt;Value&gt; | SelectAction) =&gt; void"
       },
       "required": true
     },
diff --git a/docs/pages/base/api/use-tabs-list.json b/docs/pages/base/api/use-tabs-list.json
index 0b22563206d23a..3c782a740b3fd3 100644
--- a/docs/pages/base/api/use-tabs-list.json
+++ b/docs/pages/base/api/use-tabs-list.json
@@ -10,6 +10,13 @@
       "type": { "name": "TabsListProviderValue", "description": "TabsListProviderValue" },
       "required": true
     },
+    "dispatch": {
+      "type": {
+        "name": "(action: ListAction&lt;string | number&gt;) =&gt; void",
+        "description": "(action: ListAction&lt;string | number&gt;) =&gt; void"
+      },
+      "required": true
+    },
     "getRootProps": {
       "type": {
         "name": "&lt;TOther extends Record&lt;string, any&gt; = {}&gt;(externalProps?: TOther) =&gt; UseTabsListRootSlotProps&lt;TOther&gt;",
diff --git a/docs/translations/api-docs/use-menu/use-menu.json b/docs/translations/api-docs/use-menu/use-menu.json
index fa42446d3bd622..28fc5be0ea60b0 100644
--- a/docs/translations/api-docs/use-menu/use-menu.json
+++ b/docs/translations/api-docs/use-menu/use-menu.json
@@ -11,7 +11,7 @@
     "contextValue": "The value to be passed into the MenuProvider.",
     "dispatch": "Action dispatcher for the menu component.\nAllows to programmatically control the menu.",
     "getListboxProps": "Resolver for the listbox component's props.",
-    "highlightedOption": "The highlighted option in the menu listbox.",
+    "highlightedValue": "The highlighted option in the menu listbox.",
     "menuItems": "Items in the menu listbox.",
     "open": "If <code>true</code>, the menu is open."
   }
diff --git a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
index 6f728d6f14478c..eb1cbcd966bb1a 100644
--- a/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
+++ b/docs/translations/api-docs/use-tabs-list/use-tabs-list.json
@@ -3,6 +3,7 @@
   "parametersDescriptions": { "ref": "Ref to the root element." },
   "returnValueDescriptions": {
     "contextValue": "The value to be passed to the TabListProvider above all the tabs.",
+    "dispatch": "Action dispatcher for the tabs list component.\nAllows to programmatically control the tabs list.",
     "getRootProps": "Resolver for the root slot's props.",
     "highlightedValue": "The value of the currently highlighted tab.",
     "isRtl": "If <code>true</code>, it will indicate that the text's direction in right-to-left.",

From 6070647410ddf11eeedeffe98948c12889d08b43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@dudak.me>
Date: Tue, 11 Apr 2023 15:55:53 +0200
Subject: [PATCH 49/49] Change selectionLimit to selectionMode

---
 docs/pages/experiments/base/listbox.tsx       |  2 +-
 .../mui-base/src/useList/listReducer.test.ts  | 84 +++++++------------
 packages/mui-base/src/useList/listReducer.ts  | 28 +++----
 packages/mui-base/src/useList/useList.ts      |  6 +-
 .../mui-base/src/useList/useList.types.ts     | 12 +--
 packages/mui-base/src/useMenu/useMenu.ts      |  2 +-
 .../src/useSelect/selectReducer.test.ts       | 34 +++-----
 .../mui-base/src/useSelect/selectReducer.ts   | 17 ++--
 packages/mui-base/src/useSelect/useSelect.ts  |  2 +-
 .../mui-base/src/useTabsList/useTabsList.ts   |  2 +-
 10 files changed, 68 insertions(+), 121 deletions(-)

diff --git a/docs/pages/experiments/base/listbox.tsx b/docs/pages/experiments/base/listbox.tsx
index 5f6a5c31a7f9ca..3d87ee935df0c9 100644
--- a/docs/pages/experiments/base/listbox.tsx
+++ b/docs/pages/experiments/base/listbox.tsx
@@ -137,7 +137,7 @@ function List() {
     getItemId: React.useCallback((item: number) => `item-${item}`, []),
     orientation,
     focusManagement,
-    selectionLimit: 1,
+    selectionMode: 'single',
   });
 
   const {
diff --git a/packages/mui-base/src/useList/listReducer.test.ts b/packages/mui-base/src/useList/listReducer.test.ts
index d4c7b93ef0d176..867795d3c6d10a 100644
--- a/packages/mui-base/src/useList/listReducer.test.ts
+++ b/packages/mui-base/src/useList/listReducer.test.ts
@@ -25,7 +25,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -54,7 +54,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
         item: 'two',
       };
@@ -63,7 +63,7 @@ describe('listReducer', () => {
       expect(result.selectedValues).to.deep.equal(['two']);
     });
 
-    it('replaces the selectedValues with the clicked value if selectionLimit = 1', () => {
+    it('replaces the selectedValues with the clicked value if selectionMode = "single"', () => {
       const state: ListState<string> = {
         highlightedValue: 'a',
         selectedValues: ['one'],
@@ -82,7 +82,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: 1,
+          selectionMode: 'single',
         },
         item: 'two',
       };
@@ -91,7 +91,7 @@ describe('listReducer', () => {
       expect(result.selectedValues).to.deep.equal(['two']);
     });
 
-    it('add the clicked value to the selection if selectionLimit is not set', () => {
+    it('add the clicked value to the selection if selectionMode = "multiple"', () => {
       const state: ListState<string> = {
         highlightedValue: 'one',
         selectedValues: ['one'],
@@ -110,7 +110,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'multiple',
         },
         item: 'two',
       };
@@ -119,7 +119,7 @@ describe('listReducer', () => {
       expect(result.selectedValues).to.deep.equal(['one', 'two']);
     });
 
-    it('limits the selection to specified number of items', () => {
+    it('remove the clicked value from the selection if selectionMode = "multiple" and it was selected already', () => {
       const state: ListState<string> = {
         highlightedValue: 'three',
         selectedValues: ['one', 'two'],
@@ -127,8 +127,7 @@ describe('listReducer', () => {
 
       const action: ListReducerAction<string> = {
         type: ListActionTypes.itemClick,
-        event: {} as any,
-        item: 'three',
+        event: {} as any, // not relevant
         context: {
           items: ['one', 'two', 'three'],
           disableListWrap: false,
@@ -139,18 +138,19 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: 2,
+          selectionMode: 'multiple',
         },
+        item: 'two',
       };
 
       const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['two', 'three']);
+      expect(result.selectedValues).to.deep.equal(['one']);
     });
 
-    it('remove the clicked value from the selection if selectionLimit is not set and it was selected already', () => {
+    it('does not select the clicked value to the selection if selectionMode = "none"', () => {
       const state: ListState<string> = {
-        highlightedValue: 'three',
-        selectedValues: ['one', 'two'],
+        highlightedValue: 'one',
+        selectedValues: [],
       };
 
       const action: ListReducerAction<string> = {
@@ -166,13 +166,13 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'none',
         },
         item: 'two',
       };
 
       const result = listReducer(state, action);
-      expect(result.selectedValues).to.deep.equal(['one']);
+      expect(result.selectedValues).to.deep.equal([]);
     });
   });
 
@@ -576,7 +576,7 @@ describe('listReducer', () => {
               itemStringifier: (option) => option,
               orientation: 'vertical',
               pageSize: 3,
-              selectionLimit: null,
+              selectionMode: 'single',
             },
           };
 
@@ -607,7 +607,7 @@ describe('listReducer', () => {
             itemStringifier: (option) => option,
             orientation: 'vertical',
             pageSize: 5,
-            selectionLimit: null,
+            selectionMode: 'single',
           },
         };
 
@@ -615,7 +615,7 @@ describe('listReducer', () => {
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
-      it('replaces the selectedValues with the highlighted value if selectionLimit = 1', () => {
+      it('replaces the selectedValues with the highlighted value if selectionMode = "single"', () => {
         const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
@@ -635,7 +635,7 @@ describe('listReducer', () => {
             itemStringifier: (option) => option,
             orientation: 'vertical',
             pageSize: 5,
-            selectionLimit: 1,
+            selectionMode: 'single',
           },
         };
 
@@ -643,7 +643,7 @@ describe('listReducer', () => {
         expect(result.selectedValues).to.deep.equal(['two']);
       });
 
-      it('add the highlighted value to the selection if selectionLimit is not set', () => {
+      it('add the highlighted value to the selection if selectionMode = "multiple"', () => {
         const state: ListState<string> = {
           highlightedValue: 'two',
           selectedValues: ['one'],
@@ -663,41 +663,13 @@ describe('listReducer', () => {
             itemStringifier: (option) => option,
             orientation: 'vertical',
             pageSize: 5,
-            selectionLimit: null,
+            selectionMode: 'multiple',
           },
         };
 
         const result = listReducer(state, action);
         expect(result.selectedValues).to.deep.equal(['one', 'two']);
       });
-
-      it('limits the selection to specified number of items', () => {
-        const state: ListState<string> = {
-          highlightedValue: 'three',
-          selectedValues: ['one', 'two'],
-        };
-
-        const action: ListReducerAction<string> = {
-          type: ListActionTypes.keyDown,
-          key: 'Enter',
-          event: {} as any,
-          context: {
-            items: ['one', 'two', 'three'],
-            disableListWrap: false,
-            disabledItemsFocusable: false,
-            focusManagement: 'activeDescendant',
-            isItemDisabled: () => false,
-            itemComparer: (o, v) => o === v,
-            itemStringifier: (option) => option,
-            orientation: 'vertical',
-            pageSize: 5,
-            selectionLimit: 2,
-          },
-        };
-
-        const result = listReducer(state, action);
-        expect(result.selectedValues).to.deep.equal(['two', 'three']);
-      });
     });
   });
 
@@ -722,7 +694,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -750,7 +722,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -778,7 +750,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -806,7 +778,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -834,7 +806,7 @@ describe('listReducer', () => {
           itemStringifier: (option) => option,
           orientation: 'vertical',
           pageSize: 5,
-          selectionLimit: null,
+          selectionMode: 'single',
         },
       };
 
@@ -852,7 +824,7 @@ describe('listReducer', () => {
       itemStringifier: (option: any) => option,
       orientation: 'vertical' as const,
       pageSize: 5,
-      selectionLimit: null,
+      selectionMode: 'single' as const,
     };
 
     describe('using default item comparer', () => {
diff --git a/packages/mui-base/src/useList/listReducer.ts b/packages/mui-base/src/useList/listReducer.ts
index 8fd7ec49f6e5b2..e19db122dd0984 100644
--- a/packages/mui-base/src/useList/listReducer.ts
+++ b/packages/mui-base/src/useList/listReducer.ts
@@ -1,5 +1,5 @@
 import { ListActionTypes } from './listActions.types';
-import { ListState, ListReducerAction, ListActionContext } from './useList.types';
+import { ListState, ListReducerAction, ListActionContext, SelectionMode } from './useList.types';
 
 type ItemPredicate<ItemValue> = (item: ItemValue, index: number) => boolean;
 
@@ -167,7 +167,7 @@ export function moveHighlight<ItemValue>(
  *
  * @param item Item to toggle.
  * @param selectedValues Already selected items.
- * @param selectionLimit The number of items that can be simultanously selected. If null, there is no limit.
+ * @param selectionMode The number of items that can be simultanously selected.
  * @param itemComparer A custom item comparer function.
  *
  * @returns The new array of selected items.
@@ -175,15 +175,15 @@ export function moveHighlight<ItemValue>(
 export function toggleSelection<ItemValue>(
   item: ItemValue,
   selectedValues: ItemValue[],
-  selectionLimit: number | null,
+  selectionMode: SelectionMode,
   itemComparer: (item1: ItemValue, item2: ItemValue) => boolean,
 ) {
-  if (selectionLimit === 0) {
+  if (selectionMode === 'none') {
     return [];
   }
 
-  // Selection limit = 1 is a special case - we don't want to allow deselecting the item.
-  if (selectionLimit === 1) {
+  if (selectionMode === 'single') {
+    // if the item to select has already been selected, return the original array
     if (itemComparer(selectedValues[0], item)) {
       return selectedValues;
     }
@@ -196,16 +196,8 @@ export function toggleSelection<ItemValue>(
     return selectedValues.filter((sv) => !itemComparer(sv, item));
   }
 
-  // The toggled item is not selected and the selected array is shorter than the limit - add to the selection.
-  if (selectionLimit === null || selectedValues.length < selectionLimit) {
-    return [...selectedValues, item];
-  }
-
-  // Truncate the selection to the limit (discard items with lower indexes).
-  const newSelection = selectedValues.slice(selectedValues.length - selectionLimit + 1);
-  newSelection.push(item);
-
-  return newSelection;
+  // The toggled item is not selected - add it to the selection.
+  return [...selectedValues, item];
 }
 
 function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
@@ -213,7 +205,7 @@ function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
   state: State,
   context: ListActionContext<ItemValue>,
 ): State {
-  const { itemComparer, isItemDisabled, selectionLimit, items } = context;
+  const { itemComparer, isItemDisabled, selectionMode, items } = context;
   const { selectedValues } = state;
 
   const itemIndex = items.findIndex((i) => itemComparer(item, i));
@@ -223,7 +215,7 @@ function handleItemSelection<ItemValue, State extends ListState<ItemValue>>(
   }
 
   // if the item is already selected, remove it from the selection, otherwise add it
-  const newSelectedValues = toggleSelection(item, selectedValues, selectionLimit, itemComparer);
+  const newSelectedValues = toggleSelection(item, selectedValues, selectionMode, itemComparer);
 
   return {
     ...state,
diff --git a/packages/mui-base/src/useList/useList.ts b/packages/mui-base/src/useList/useList.ts
index 34a39538d7cfe0..84dbb6724d744b 100644
--- a/packages/mui-base/src/useList/useList.ts
+++ b/packages/mui-base/src/useList/useList.ts
@@ -82,7 +82,7 @@ function useList<
     orientation = 'vertical',
     pageSize = 5,
     reducerActionContext = EMPTY_OBJECT as CustomActionContext,
-    selectionLimit = null,
+    selectionMode = 'single',
     stateReducer: externalReducer,
   } = params;
 
@@ -175,7 +175,7 @@ function useList<
       onHighlightChange: handleHighlightChange,
       orientation,
       pageSize,
-      selectionLimit,
+      selectionMode,
       stateComparers,
     };
   }, [
@@ -189,7 +189,7 @@ function useList<
     handleHighlightChange,
     orientation,
     pageSize,
-    selectionLimit,
+    selectionMode,
     stateComparers,
   ]);
 
diff --git a/packages/mui-base/src/useList/useList.types.ts b/packages/mui-base/src/useList/useList.types.ts
index 3f004a6a1810ad..81710216dd42c9 100644
--- a/packages/mui-base/src/useList/useList.types.ts
+++ b/packages/mui-base/src/useList/useList.types.ts
@@ -17,7 +17,7 @@ type ListActionContextRequiredKeys =
   | 'itemStringifier'
   | 'orientation'
   | 'pageSize'
-  | 'selectionLimit';
+  | 'selectionMode';
 
 /**
  * The subset of `UseListParameters` that is passed to the list reducer actions.
@@ -67,6 +67,8 @@ export type ListReducer<ItemValue, State extends ListState<ItemValue>, CustomAct
 
 export type FocusManagementType = 'DOM' | 'activeDescendant';
 
+export type SelectionMode = 'none' | 'single' | 'multiple';
+
 /**
  * Parameters of the useList hook.
  *
@@ -189,12 +191,10 @@ export interface UseListParameters<
    */
   orientation?: 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
   /**
-   * Maximum number of items that can be selected at once.
-   * Set to `null` to disable the limit.
-   *
-   * @default null
+   * Controls how many items can be selected at once: none (the selection functionality is disabled in this case), one, or indefinitely many.
+   * @default 'single'
    */
-  selectionLimit?: number | null;
+  selectionMode?: SelectionMode;
   /**
    * Custom state reducer function. It calculates the new state (highlighted and selected items + optional custom state)
    * based on the previous one and the performed action.
diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
index 05514292f06005..4fd00a2f15dd92 100644
--- a/packages/mui-base/src/useMenu/useMenu.ts
+++ b/packages/mui-base/src/useMenu/useMenu.ts
@@ -84,7 +84,7 @@ export default function useMenu(parameters: UseMenuParameters = {}): UseMenuRetu
     listRef: handleRef,
     onStateChange: stateChangeHandler,
     reducerActionContext: { listboxRef },
-    selectionLimit: 0,
+    selectionMode: 'none',
     stateReducer: menuReducer,
   });
 
diff --git a/packages/mui-base/src/useSelect/selectReducer.test.ts b/packages/mui-base/src/useSelect/selectReducer.test.ts
index c02b876cebeaed..b83a575820291c 100644
--- a/packages/mui-base/src/useSelect/selectReducer.test.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.test.ts
@@ -1,7 +1,8 @@
 import { expect } from 'chai';
-import selectReducer, { SelectActionContext } from './selectReducer';
+import selectReducer from './selectReducer';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
 import { ActionWithContext } from '../utils/useControllableReducer.types';
+import { ListActionContext } from '../useList';
 
 describe('selectReducer', () => {
   const irrelevantConfig = {
@@ -14,7 +15,7 @@ describe('selectReducer', () => {
     itemStringifier: (option: any) => option,
     orientation: 'vertical' as const,
     pageSize: 5,
-    selectionLimit: null,
+    selectionMode: 'single' as const,
   };
 
   describe('action: buttonClick', () => {
@@ -25,13 +26,10 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
+      const action: ActionWithContext<SelectAction, ListActionContext<unknown>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
-        context: {
-          ...irrelevantConfig,
-          multiple: false,
-        },
+        context: irrelevantConfig,
       };
 
       const result = selectReducer(state, action);
@@ -45,12 +43,11 @@ describe('selectReducer', () => {
         open: true,
       };
 
-      const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
+      const action: ActionWithContext<SelectAction, ListActionContext<unknown>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
           ...irrelevantConfig,
-          multiple: false,
         },
       };
 
@@ -65,13 +62,12 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
+      const action: ActionWithContext<SelectAction, ListActionContext<string>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
           ...irrelevantConfig,
           items: ['1', '2', '3'],
-          multiple: false,
         },
       };
 
@@ -86,13 +82,12 @@ describe('selectReducer', () => {
         open: false,
       };
 
-      const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
+      const action: ActionWithContext<SelectAction, ListActionContext<string>> = {
         type: SelectActionTypes.buttonClick,
         event: {} as any, // not relevant
         context: {
           ...irrelevantConfig,
           items: ['1', '2', '3'],
-          multiple: false,
         },
       };
 
@@ -114,14 +109,11 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: ActionWithContext<SelectAction, SelectActionContext<unknown>> = {
+          const action: ActionWithContext<SelectAction, ListActionContext<unknown>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
-            context: {
-              ...irrelevantConfig,
-              multiple: false,
-            },
+            context: irrelevantConfig,
           };
 
           const result = selectReducer(state, action);
@@ -135,14 +127,13 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
+          const action: ActionWithContext<SelectAction, ListActionContext<string>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
             context: {
               ...irrelevantConfig,
               items: ['1', '2', '3'],
-              multiple: false,
             },
           };
 
@@ -157,14 +148,13 @@ describe('selectReducer', () => {
             open: false,
           };
 
-          const action: ActionWithContext<SelectAction, SelectActionContext<string>> = {
+          const action: ActionWithContext<SelectAction, ListActionContext<string>> = {
             type: SelectActionTypes.buttonArrowKeyDown,
             key: testCase.key,
             event: {} as any, // not relevant
             context: {
               ...irrelevantConfig,
               items: ['1', '2', '3'],
-              multiple: false,
             },
           };
 
diff --git a/packages/mui-base/src/useSelect/selectReducer.ts b/packages/mui-base/src/useSelect/selectReducer.ts
index 9ca118ea1d1496..839b9e499cc6e9 100644
--- a/packages/mui-base/src/useSelect/selectReducer.ts
+++ b/packages/mui-base/src/useSelect/selectReducer.ts
@@ -8,20 +8,13 @@ import {
 import { ActionWithContext } from '../utils/useControllableReducer.types';
 import { SelectAction, SelectActionTypes, SelectInternalState } from './useSelect.types';
 
-export type SelectActionContext<OptionValue> = ListActionContext<OptionValue> & {
-  multiple: boolean;
-};
-
 export default function selectReducer<OptionValue>(
   state: SelectInternalState<OptionValue>,
-  action: ActionWithContext<
-    ListAction<OptionValue> | SelectAction,
-    SelectActionContext<OptionValue>
-  >,
+  action: ActionWithContext<ListAction<OptionValue> | SelectAction, ListActionContext<OptionValue>>,
 ) {
   const { open } = state;
   const {
-    context: { multiple },
+    context: { selectionMode },
   } = action;
 
   switch (action.type) {
@@ -67,13 +60,13 @@ export default function selectReducer<OptionValue>(
 
   const newState: SelectInternalState<OptionValue> = listReducer(
     state,
-    action as ActionWithContext<ListAction<OptionValue>, SelectActionContext<OptionValue>>,
+    action as ActionWithContext<ListAction<OptionValue>, ListActionContext<OptionValue>>,
   );
 
   switch (action.type) {
     case ListActionTypes.keyDown:
       if (
-        !multiple &&
+        selectionMode === 'single' &&
         (action.event.key === 'Enter' || action.event.key === ' ' || action.event.key === 'Escape')
       ) {
         return {
@@ -85,7 +78,7 @@ export default function selectReducer<OptionValue>(
       break;
 
     case ListActionTypes.itemClick:
-      if (!multiple) {
+      if (selectionMode === 'single') {
         return {
           ...newState,
           open: false,
diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
index 213002c61a8193..21c1cd69130861 100644
--- a/packages/mui-base/src/useSelect/useSelect.ts
+++ b/packages/mui-base/src/useSelect/useSelect.ts
@@ -229,7 +229,7 @@ function useSelect<OptionValue, Multiple extends boolean = false>(
     reducerActionContext: React.useMemo(() => ({ multiple }), [multiple]),
     items: optionValues,
     itemStringifier: stringifyOption,
-    selectionLimit: multiple ? null : 1,
+    selectionMode: multiple ? 'multiple' : 'single',
     stateReducer: selectReducer,
   };
 
diff --git a/packages/mui-base/src/useTabsList/useTabsList.ts b/packages/mui-base/src/useTabsList/useTabsList.ts
index 34457a9d8b20f5..26f45f440de181 100644
--- a/packages/mui-base/src/useTabsList/useTabsList.ts
+++ b/packages/mui-base/src/useTabsList/useTabsList.ts
@@ -122,7 +122,7 @@ function useTabsList(parameters: UseTabsListParameters): UseTabsListReturnValue
       () => ({ selectionFollowsFocus: selectionFollowsFocus || false }),
       [selectionFollowsFocus],
     ),
-    selectionLimit: 1,
+    selectionMode: 'single',
     stateReducer: tabsListReducer,
   });