Update items traversal

Author: atomiks

docs/data/base/components/select/SelectIntroduction/system/index.js

@@ -5,13 +5,13 @@ import Check from '@mui/icons-material/Check';
 
 export default function UnstyledSelectIntroduction() {
   return (
-    <Select.Root>
+    <Select.Root value="item-2">
       <SelectTrigger>Trigger</SelectTrigger>
       <Select.Backdrop />
       <Select.Positioner alignment="start" alignmentOffset={-4}>
         <SelectPopup>
           {[...Array(100)].map((_, index) => (
-            <SelectItem key={index}>
+            <SelectItem key={index} value={`item-${index + 1}`}>
               Item {index + 1}
               <SelectItemIndicator render={<Check fontSize="small" aria-hidden />} />
             </SelectItem>

docs/data/base/components/select/SelectIntroduction/system/index.tsx

@@ -5,13 +5,13 @@ import Check from '@mui/icons-material/Check';
 
 export default function UnstyledSelectIntroduction() {
   return (
-    <Select.Root>
+    <Select.Root value="item-2">
       <SelectTrigger>Trigger</SelectTrigger>
       <Select.Backdrop />
       <Select.Positioner alignment="start" alignmentOffset={-4}>
         <SelectPopup>
           {[...Array(100)].map((_, index) => (
-            <SelectItem key={index}>
+            <SelectItem key={index} value={`item-${index + 1}`}>
               Item {index + 1}
               <SelectItemIndicator render={<Check fontSize="small" aria-hidden />} />
             </SelectItem>

docs/data/base/components/select/SelectIntroduction/system/index.tsx.preview

@@ -1,10 +1,10 @@
-<Select.Root>
+<Select.Root value="item-2">
   <SelectTrigger>Trigger</SelectTrigger>
   <Select.Backdrop />
   <Select.Positioner alignment="start" alignmentOffset={-4}>
     <SelectPopup>
       {[...Array(100)].map((_, index) => (
-        <SelectItem key={index}>
+        <SelectItem key={index} value={`item-${index + 1}`}>
           Item {index + 1}
           <SelectItemIndicator render={<Check fontSize="small" aria-hidden />} />
         </SelectItem>

docs/pages/base-ui/api/select-item.json

@@ -1,5 +1,6 @@
 {
   "props": {
+    "value": { "type": { "name": "string" }, "required": true },
     "closeOnClick": { "type": { "name": "bool" }, "default": "true" },
     "disabled": { "type": { "name": "bool" }, "default": "false" },
     "id": { "type": { "name": "string" } },

docs/pages/base-ui/api/select-root.json

@@ -6,10 +6,16 @@
     },
     "animated": { "type": { "name": "bool" }, "default": "true" },
     "defaultOpen": { "type": { "name": "bool" }, "default": "false" },
+    "defaultValue": { "type": { "name": "string" } },
     "disabled": { "type": { "name": "bool" }, "default": "false" },
+    "id": { "type": { "name": "string" } },
     "loop": { "type": { "name": "bool" }, "default": "true" },
+    "name": { "type": { "name": "string" } },
     "onOpenChange": { "type": { "name": "func" } },
-    "open": { "type": { "name": "bool" } }
+    "open": { "type": { "name": "bool" } },
+    "readOnly": { "type": { "name": "bool" }, "default": "false" },
+    "required": { "type": { "name": "bool" }, "default": "false" },
+    "value": { "type": { "name": "string" } }
   },
   "name": "SelectRoot",
   "imports": ["import * as Select from '@base_ui/react/Select';\nconst SelectRoot = Select.Root;"],

docs/translations/api-docs/select-item/select-item.json

@@ -1,15 +1,16 @@
 {
-  "componentDescription": "An unstyled menu item to be used within a Menu.",
+  "componentDescription": "An unstyled select item to be used within a Select.",
   "propDescriptions": {
     "closeOnClick": {
-      "description": "If <code>true</code>, the menu will close when the menu item is clicked."
+      "description": "If <code>true</code>, the select will close when the select item is clicked."
     },
-    "disabled": { "description": "If <code>true</code>, the menu item will be disabled." },
-    "id": { "description": "The id of the menu item." },
+    "disabled": { "description": "If <code>true</code>, the select item will be disabled." },
+    "id": { "description": "The id of the select item." },
     "label": {
-      "description": "A text representation of the menu item&#39;s content. Used for keyboard text navigation matching."
+      "description": "A text representation of the select item&#39;s content. Used for keyboard text navigation matching."
     },
-    "onClick": { "description": "The click handler for the menu item." }
+    "onClick": { "description": "The click handler for the select item." },
+    "value": { "description": "The value of the select item." }
   },
   "classDescriptions": {}
 }

docs/translations/api-docs/select-root/select-root.json

@@ -5,19 +5,25 @@
       "description": "Determines the type of alignment mode. <code>selected-item</code> aligns the popup so that the selected item appears over the trigger, while <code>trigger</code> aligns the popup using standard anchor positioning."
     },
     "animated": {
-      "description": "If <code>true</code>, the Menu supports CSS-based animations and transitions. It is kept in the DOM until the animation completes."
+      "description": "If <code>true</code>, the Select supports CSS-based animations and transitions. It is kept in the DOM until the animation completes."
     },
-    "defaultOpen": { "description": "If <code>true</code>, the Menu is initially open." },
-    "disabled": { "description": "If <code>true</code>, the Menu is disabled." },
+    "defaultOpen": { "description": "If <code>true</code>, the Select is initially open." },
+    "defaultValue": { "description": "The default value of the select." },
+    "disabled": { "description": "If <code>true</code>, the Select is disabled." },
+    "id": { "description": "The id of the Select." },
     "loop": {
       "description": "If <code>true</code>, using keyboard navigation will wrap focus to the other end of the list once the end is reached."
     },
+    "name": { "description": "The name of the Select in the owning form." },
     "onOpenChange": {
       "description": "Callback fired when the component requests to be opened or closed."
     },
     "open": {
       "description": "Allows to control whether the dropdown is open. This is a controlled counterpart of <code>defaultOpen</code>."
-    }
+    },
+    "readOnly": { "description": "If <code>true</code>, the Select is read-only." },
+    "required": { "description": "If <code>true</code>, the Select is required." },
+    "value": { "description": "The value of the select." }
   },
   "classDescriptions": {}
 }

packages/mui-base/src/Select/Item/SelectItem.tsx

@@ -11,6 +11,7 @@ import { useForkRef } from '../../utils/useForkRef';
 import { useEventCallback } from '../../utils/useEventCallback';
 import { SelectItemContext } from './SelectItemContext';
 import { commonStyleHooks } from '../utils/commonStyleHooks';
+import { useEnhancedEffect } from '../../utils/useEnhancedEffect';
 
 const InnerSelectItem = React.memo(
   React.forwardRef(function InnerSelectItem(
@@ -74,44 +75,59 @@ const InnerSelectItem = React.memo(
 );
 
 /**
- * An unstyled menu item to be used within a Menu.
+ * An unstyled select item to be used within a Select.
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/)
+ * - [Select](https://mui.com/base-ui/react-select/)
  *
  * API:
  *
- * - [SelectItem API](https://mui.com/base-ui/react-menu/components-api/#menu-item)
+ * - [SelectItem API](https://mui.com/base-ui/react-select/components-api/#select-item)
  */
 const SelectItem = React.forwardRef(function SelectItem(
   props: SelectItem.Props,
   forwardedRef: React.ForwardedRef<Element>,
 ) {
-  const { id: idProp, label, ...otherProps } = props;
+  const { id: idProp, value: valueProp, label, ...otherProps } = props;
 
   const {
+    setValue,
     open,
     getItemProps,
     activeIndex,
     selectedIndex,
     setOpen,
     typingRef,
-    setSelectedIndex,
     selectionRef,
+    valuesRef,
   } = useSelectRootContext();
 
   const [item, setItem] = React.useState<Element | null>(null);
-  const listItem = useListItem({ label: label ?? item?.textContent });
+  const itemLabel = label ?? item?.textContent ?? null;
+  const listItem = useListItem({ label: itemLabel });
   const mergedRef = useForkRef(forwardedRef, listItem.ref, setItem);
 
+  useEnhancedEffect(() => {
+    if (listItem.index === -1) {
+      return undefined;
+    }
+
+    const values = valuesRef.current;
+    values[listItem.index] = valueProp;
+
+    return () => {
+      values[listItem.index] = null;
+    };
+  }, [listItem.index, valueProp, valuesRef]);
+
   const id = useId(idProp);
 
   const highlighted = listItem.index === activeIndex;
   const selected = listItem.index === selectedIndex;
 
   const handleSelect = useEventCallback(() => {
-    setSelectedIndex(listItem.index);
+    setValue(valueProp);
   });
 
   const contextValue = React.useMemo(() => ({ open, selected }), [open, selected]);
@@ -139,7 +155,7 @@ const SelectItem = React.forwardRef(function SelectItem(
   );
 });
 
-interface InnerSelectItemProps extends SelectItem.Props {
+interface InnerSelectItemProps extends Omit<SelectItem.Props, 'value'> {
   highlighted: boolean;
   selected: boolean;
   getItemProps: UseInteractionsReturn['getItemProps'];
@@ -164,25 +180,29 @@ namespace SelectItem {
   export interface Props extends BaseUIComponentProps<'div', OwnerState> {
     children?: React.ReactNode;
     /**
-     * The click handler for the menu item.
+     * The value of the select item.
+     */
+    value: string;
+    /**
+     * The click handler for the select item.
      */
     onClick?: React.MouseEventHandler<HTMLElement>;
     /**
-     * If `true`, the menu item will be disabled.
+     * If `true`, the select item will be disabled.
      * @default false
      */
     disabled?: boolean;
     /**
-     * A text representation of the menu item's content.
+     * A text representation of the select item's content.
      * Used for keyboard text navigation matching.
      */
     label?: string;
     /**
-     * The id of the menu item.
+     * The id of the select item.
      */
     id?: string;
     /**
-     * If `true`, the menu will close when the menu item is clicked.
+     * If `true`, the select will close when the select item is clicked.
      *
      * @default true
      */
@@ -200,29 +220,33 @@ SelectItem.propTypes /* remove-proptypes */ = {
    */
   children: PropTypes.node,
   /**
-   * If `true`, the menu will close when the menu item is clicked.
+   * If `true`, the select will close when the select item is clicked.
    *
    * @default true
    */
   closeOnClick: PropTypes.bool,
   /**
-   * If `true`, the menu item will be disabled.
+   * If `true`, the select item will be disabled.
    * @default false
    */
   disabled: PropTypes.bool,
   /**
-   * The id of the menu item.
+   * The id of the select item.
    */
   id: PropTypes.string,
   /**
-   * A text representation of the menu item's content.
+   * A text representation of the select item's content.
    * Used for keyboard text navigation matching.
    */
   label: PropTypes.string,
   /**
-   * The click handler for the menu item.
+   * The click handler for the select item.
    */
   onClick: PropTypes.func,
+  /**
+   * The value of the select item.
+   */
+  value: PropTypes.string.isRequired,
 } as any;
 
 export { SelectItem };

packages/mui-base/src/Select/Item/useSelectItem.ts

@@ -16,7 +16,6 @@ export function useSelectItem(params: useSelectItem.Parameters): useSelectItem.R
   const {
     disabled = false,
     highlighted,
-    selected,
     id,
     ref: externalRef,
     setOpen,
@@ -69,11 +68,7 @@ export function useSelectItem(params: useSelectItem.Parameters): useSelectItem.R
               return;
             }
 
-            if (selected) {
-              if (selectionRef.current.select) {
-                commitSelection(event.nativeEvent);
-              }
-            } else {
+            if (selectionRef.current.select) {
               commitSelection(event.nativeEvent);
             }
 
@@ -82,7 +77,7 @@ export function useSelectItem(params: useSelectItem.Parameters): useSelectItem.R
         }),
       );
     },
-    [commitSelection, getButtonProps, highlighted, id, selected, selectionRef, typingRef],
+    [commitSelection, getButtonProps, highlighted, id, selectionRef, typingRef],
   );
 
   return React.useMemo(