[utils] Explicitly register roving tab items with parent

docs/data/material/components/menus/GroupedMenu.js

@@ -5,18 +5,9 @@ import Menu from '@mui/material/Menu';
 import MenuItem from '@mui/material/MenuItem';
 import { styled } from '@mui/material/styles';
 
-const StyledListHeader = Object.assign(
-  styled(ListSubheader)({
-    backgroundImage: 'var(--Paper-overlay)',
-  }),
-  {
-    // IMPORTANT: The base ListSubheader component sets `muiSkipListHighlight = true`
-    // by default, but wrapping it with `styled(ListSubheader)` does not preserve
-    // that static field. We re-declare it here so the menu list continues to skip
-    // highlighting this non-focusable subheader when navigating with the keyboard.
-    muiSkipListHighlight: true,
-  },
-);
+const StyledListHeader = styled(ListSubheader)({
+  backgroundImage: 'var(--Paper-overlay)',
+});
 
 export default function GroupedMenu() {
   const [anchorEl, setAnchorEl] = React.useState(null);

docs/data/material/components/menus/GroupedMenu.tsx

@@ -5,18 +5,9 @@ import Menu from '@mui/material/Menu';
 import MenuItem from '@mui/material/MenuItem';
 import { styled } from '@mui/material/styles';
 
-const StyledListHeader = Object.assign(
-  styled(ListSubheader)({
-    backgroundImage: 'var(--Paper-overlay)',
-  }),
-  {
-    // IMPORTANT: The base ListSubheader component sets `muiSkipListHighlight = true`
-    // by default, but wrapping it with `styled(ListSubheader)` does not preserve
-    // that static field. We re-declare it here so the menu list continues to skip
-    // highlighting this non-focusable subheader when navigating with the keyboard.
-    muiSkipListHighlight: true,
-  },
-);
+const StyledListHeader = styled(ListSubheader)({
+  backgroundImage: 'var(--Paper-overlay)',
+});
 
 export default function GroupedMenu() {
   const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);

docs/data/material/components/selects/selects.md

@@ -141,67 +141,6 @@ Display categories with the `ListSubheader` component or the native `<optgroup>`
 
 {{"demo": "GroupedSelect.js"}}
 
-:::warning
-If you wish to wrap the ListSubheader in a custom component, you'll have to annotate it so Material UI can handle it properly when determining focusable elements.
-
-You have two options for solving this:
-Option 1: Define a static boolean field called `muiSkipListHighlight` on your component function, and set it to `true`:
-
-```tsx
-function MyListSubheader(props: ListSubheaderProps) {
-  return <ListSubheader {...props} />;
-}
-
-MyListSubheader.muiSkipListHighlight = true;
-export default MyListSubheader;
-
-// elsewhere:
-
-return (
-  <Select>
-    <MyListSubheader>Group 1</MyListSubheader>
-    <MenuItem value={1}>Option 1</MenuItem>
-    <MenuItem value={2}>Option 2</MenuItem>
-    <MyListSubheader>Group 2</MyListSubheader>
-    <MenuItem value={3}>Option 3</MenuItem>
-    <MenuItem value={4}>Option 4</MenuItem>
-    {/* ... */}
-  </Select>
-```
-
-Option 2: Place a `muiSkipListHighlight` prop on each instance of your component.
-The prop doesn't have to be forwarded to the ListSubheader, nor present in the underlying DOM element.
-It just has to be placed on a component that's used as a subheader.
-
-```tsx
-export default function MyListSubheader(
-  props: ListSubheaderProps & { muiSkipListHighlight: boolean },
-) {
-  const { muiSkipListHighlight, ...other } = props;
-  return <ListSubheader {...other} />;
-}
-
-// elsewhere:
-
-return (
-  <Select>
-    <MyListSubheader muiSkipListHighlight>Group 1</MyListSubheader>
-    <MenuItem value={1}>Option 1</MenuItem>
-    <MenuItem value={2}>Option 2</MenuItem>
-    <MyListSubheader muiSkipListHighlight>Group 2</MyListSubheader>
-    <MenuItem value={3}>Option 3</MenuItem>
-    <MenuItem value={4}>Option 4</MenuItem>
-    {/* ... */}
-  </Select>
-);
-```
-
-We recommend the first option as it doesn't require updating all the usage sites of the component.
-
-Keep in mind this is **only necessary** if you wrap the ListSubheader in a custom component.
-If you use the ListSubheader directly, **no additional code is required**.
-:::
-
 ## Accessibility
 
 To properly label your `Select` input you need an extra element with an `id` that contains a label.

docs/data/material/migration/upgrade-to-v9/upgrade-to-v9.md

@@ -270,20 +270,26 @@ The `StepButton` has:
 
 ### Tabs
 
-The `tabindex` attribute for each tab will be changed on Arrow Key or Home / End navigation. Previously, we only moved the focus on keyboard navigation. Now, we move the focus and also add the `tabindex="0"` to the focused element. The previously focused element will have its `tabindex` updated to `-1` in order to keep only one focusable `Tab` at a time.
+The `tabindex` attribute for each tab will be changed on Arrow Key or Home / End navigation. Previously, keyboard navigation moved DOM focus without updating `tabindex` on the focused `Tab`. Now, we move DOM focus and also add the `tabindex="0"` to the focused `Tab`. Other tabs will have `tabindex="-1"` to keep only one focusable `Tab` at a time.
 
 Selecting a `Tab` will update the focus and `tabindex` as before.
 
-### Menu and MenuList
+`Tab`s not placed inside `Tabs` will now throw an error.
 
-The `tabindex` attribute for each menu item will be changed on Arrow Key, Home / End or Character Key navigation. Previously, we only moved the focus on keyboard navigation. Now, we move the focus and also add the `tabindex="0"` to the focused element. The previously focused element will have its `tabindex` updated to `-1` in order to keep only one focusable `MenuItem` at a time.
+### Menu and MenuList
 
-This change also applies to the `Menu` since it uses `MenuList`.
+When using `variant="selectedMenu"`, the `tabindex` attribute for each menu item will change on Arrow Key, Home / End or Character Key navigation. Previously, keyboard navigation moved DOM focus without updating `tabindex` on focused items. Now, we move DOM focus and also add `tabindex="0"` to the focused element. The previously focused element will have its `tabindex` updated to `-1` in order to keep only one focusable `MenuItem` at a time.
 
-Selecting a `MenuItem` will update the focus and `tabindex` as before.
+This change also applies both `Menu` and `MenuList` with `variant="selectedMenu"`.
 
 The `autoFocus` prop in `MenuList` does not set `tabindex="0"` on the `List` component anymore. It will always stay as `-1`.
 
+`MenuItem`s will throw an error when rendered outside of `Menu` or `MenuList`.
+
+Custom non-interactive menu content such as `ListSubheader` or `Divider` no longer need to set `muiSkipListHighlight` to opt-out of the menu's focus management.
+
+Custom children that set `role="menuitem"` but do not wrap the `MenuItem` component are no longer supported inside `Menu` or `MenuList`.
+
 ## Deprecated APIs removed (Breaking)
 
 APIs that were deprecated earlier have been removed in v9.

docs/pages/experiments/roving-focus.tsx

@@ -0,0 +1,229 @@
+import * as React from 'react';
+import useEventCallback from '@mui/utils/useEventCallback';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Container from '@mui/material/Container';
+import Divider from '@mui/material/Divider';
+import Menu from '@mui/material/Menu';
+import MenuItem from '@mui/material/MenuItem';
+import Paper from '@mui/material/Paper';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+import Head from 'docs/src/modules/components/Head';
+import { Link } from '@mui/docs/Link';
+
+const MenuDivider = React.forwardRef<HTMLHRElement, React.ComponentPropsWithoutRef<typeof Divider>>(
+  function MenuDivider(props, ref) {
+    return <Divider ref={ref} {...props} />;
+  },
+);
+
+interface ExampleFrameProps {
+  children: React.ReactNode;
+  eyebrow: string;
+  title: string;
+  description: string;
+  instructions: string;
+}
+
+function ExampleFrame(props: ExampleFrameProps) {
+  const { children, eyebrow, title, description, instructions } = props;
+
+  return (
+    <Paper component="section" variant="outlined" sx={{ p: 3 }}>
+      <Stack spacing={3}>
+        <div>
+          <Typography variant="overline" color="text.secondary">
+            {eyebrow}
+          </Typography>
+          <Typography variant="h6" sx={{ mt: 0.5 }}>
+            {title}
+          </Typography>
+          <Typography variant="body2" color="text.secondary" sx={{ mt: 1 }}>
+            {description}
+          </Typography>
+          <Typography variant="body2" color="text.secondary" sx={{ mt: 1 }}>
+            {instructions}
+          </Typography>
+        </div>
+        {children}
+      </Stack>
+    </Paper>
+  );
+}
+
+function FragmentAndDividerExample() {
+  const [open, setOpen] = React.useState(false);
+  const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+  const handleClose = useEventCallback(() => {
+    setOpen(false);
+  });
+
+  return (
+    <ExampleFrame
+      eyebrow="Fragments"
+      title="Fragment-wrapped items and wrapped dividers"
+      description="This menu mixes MenuItems inside React.Fragment with a Divider wrapper that used to accidentally join the tab sequence."
+      instructions='Open the menu and use the arrow keys. The selected item should land on "Pin to right", both fragment groups should participate, and the divider wrapper should be skipped entirely.'
+    >
+      <Button ref={buttonRef} variant="contained" onClick={() => setOpen(true)}>
+        Open fragment menu
+      </Button>
+      <Menu anchorEl={buttonRef.current} open={open} onClose={() => setOpen(false)}>
+        <React.Fragment>
+          <MenuItem onClick={handleClose}>Sort ascending</MenuItem>
+          <MenuItem onClick={handleClose}>Sort descending</MenuItem>
+        </React.Fragment>
+        <MenuDivider />
+        <React.Fragment>
+          {null}
+          <MenuItem onClick={handleClose}>Pin to left</MenuItem>
+          <MenuItem selected onClick={handleClose}>
+            Pin to right
+          </MenuItem>
+        </React.Fragment>
+        <MenuDivider />
+        <React.Fragment>
+          <MenuItem onClick={handleClose}>Filter</MenuItem>
+          <MenuItem onClick={handleClose}>Manage columns</MenuItem>
+        </React.Fragment>
+      </Menu>
+    </ExampleFrame>
+  );
+}
+
+function ConditionalInsertExample() {
+  const [open, setOpen] = React.useState(false);
+  const [showPinnedActions, setShowPinnedActions] = React.useState(false);
+  const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+  const handleClose = useEventCallback(() => {
+    setOpen(false);
+  });
+
+  return (
+    <ExampleFrame
+      eyebrow="Conditional Rendering"
+      title="Inserting items ahead of the active MenuItem"
+      description="This example inserts a fragment before the selected item while the menu is already open."
+      instructions='Open the menu, then toggle the extra block. Focus should stay anchored to "Reports" instead of jumping back to the start.'
+    >
+      <Stack direction="row" spacing={1.5} useFlexGap sx={{ flexWrap: 'wrap' }}>
+        <Button ref={buttonRef} variant="contained" onClick={() => setOpen(true)}>
+          Open conditional menu
+        </Button>
+        <Button variant="outlined" onClick={() => setShowPinnedActions((previous) => !previous)}>
+          {showPinnedActions ? 'Hide pinned actions' : 'Show pinned actions'}
+        </Button>
+      </Stack>
+      <Menu anchorEl={buttonRef.current} open={open} onClose={() => setOpen(false)}>
+        {showPinnedActions ? (
+          <React.Fragment>
+            <MenuItem onClick={handleClose}>Pin to dashboard</MenuItem>
+            <MenuItem onClick={handleClose}>Send to favorites</MenuItem>
+            <MenuDivider />
+          </React.Fragment>
+        ) : null}
+        <MenuItem onClick={handleClose}>Overview</MenuItem>
+        <MenuItem selected onClick={handleClose}>
+          Reports
+        </MenuItem>
+        <MenuItem onClick={handleClose}>Notifications</MenuItem>
+        <MenuItem onClick={handleClose}>History</MenuItem>
+      </Menu>
+    </ExampleFrame>
+  );
+}
+
+function ReorderingExample() {
+  const [open, setOpen] = React.useState(false);
+  const [priorityFirst, setPriorityFirst] = React.useState(true);
+  const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+  const handleClose = useEventCallback(() => {
+    setOpen(false);
+  });
+
+  const priorityGroup = (
+    <React.Fragment key="priority-group">
+      <MenuItem onClick={handleClose}>Pin to left</MenuItem>
+      <MenuItem onClick={handleClose}>Pin to right</MenuItem>
+    </React.Fragment>
+  );
+
+  const primaryGroup = (
+    <React.Fragment key="primary-group">
+      <MenuItem onClick={handleClose}>Rename</MenuItem>
+      <MenuItem selected onClick={handleClose}>
+        Duplicate
+      </MenuItem>
+      <MenuItem onClick={handleClose}>Archive</MenuItem>
+    </React.Fragment>
+  );
+
+  const orderedGroups = priorityFirst
+    ? [priorityGroup, <MenuDivider key="boundary-divider" />, primaryGroup]
+    : [primaryGroup, <MenuDivider key="boundary-divider" />, priorityGroup];
+
+  return (
+    <ExampleFrame
+      eyebrow="Internal Reordering"
+      title="Moving a whole fragment block to a different position"
+      description="This example moves an entire keyed fragment from the top of the menu to the bottom while the menu is already open."
+      instructions='Open the menu and move the priority fragment. Focus should stay on "Duplicate" even as the block moves around it.'
+    >
+      <Stack direction="row" spacing={1.5} useFlexGap sx={{ flexWrap: 'wrap' }}>
+        <Button ref={buttonRef} variant="contained" onClick={() => setOpen(true)}>
+          Open reordering menu
+        </Button>
+        <Button variant="outlined" onClick={() => setPriorityFirst((previous) => !previous)}>
+          {priorityFirst ? 'Move priority actions below' : 'Move priority actions above'}
+        </Button>
+      </Stack>
+      <Menu anchorEl={buttonRef.current} open={open} onClose={() => setOpen(false)}>
+        {orderedGroups}
+      </Menu>
+    </ExampleFrame>
+  );
+}
+
+export default function RovingFocusExperiment() {
+  return (
+    <React.Fragment>
+      <Head title="Menu Roving Focus Experiments" description="" />
+      <Box sx={{ py: { xs: 4, md: 6 } }}>
+        <Container maxWidth="md">
+          <Stack spacing={4}>
+            <Stack spacing={2}>
+              <Typography variant="overline" color="text.secondary">
+                Experiments
+              </Typography>
+              <Typography variant="h3">
+                Menu roving focus after registration-based item tracking
+              </Typography>
+              <Typography variant="body1" color="text.secondary">
+                These demos focus on the cases that were brittle before the refactor: MenuItems
+                inside fragments, wrapped dividers, and conditional child trees that reorder after
+                the menu has already resolved its active item.
+              </Typography>
+              <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap' }}>
+                <Button component={Link} href="/experiments" noLinkStyle variant="outlined">
+                  Back to experiments
+                </Button>
+                <Button
+                  component={Link}
+                  href="https://github.com/mui/material-ui/tree/master/docs/pages/experiments"
+                  noLinkStyle
+                  variant="text"
+                >
+                  Open experiments source
+                </Button>
+              </Box>
+            </Stack>
+            <FragmentAndDividerExample />
+            <ConditionalInsertExample />
+            <ReorderingExample />
+          </Stack>
+        </Container>
+      </Box>
+    </React.Fragment>
+  );
+}

docs/pages/material-ui/api/popover.json

@@ -23,6 +23,7 @@
     "children": { "type": { "name": "node" } },
     "classes": { "type": { "name": "object" }, "additionalInfo": { "cssApi": true } },
     "container": { "type": { "name": "union", "description": "HTML element<br>&#124;&nbsp;func" } },
+    "disableAutoFocus": { "type": { "name": "bool" }, "default": "false" },
     "disableScrollLock": { "type": { "name": "bool" }, "default": "false" },
     "elevation": { "type": { "name": "custom", "description": "integer" }, "default": "8" },
     "marginThreshold": { "type": { "name": "number" }, "default": "16" },

docs/translations/api-docs/popover/popover.json

@@ -21,6 +21,9 @@
     "container": {
       "description": "An HTML element, component instance, or function that returns either. The <code>container</code> will passed to the Modal component.<br>By default, it uses the body of the anchorEl&#39;s top-level document object, so it&#39;s simply <code>document.body</code> most of the time."
     },
+    "disableAutoFocus": {
+      "description": "If <code>true</code>, the modal will not automatically shift focus to itself when it opens, and replace it to the last focused element when it closes. This also works correctly with any modal children that have the <code>disableAutoFocus</code> prop.<br>Generally this should never be set to <code>true</code> as it makes the modal less accessible to assistive technologies, like screen readers."
+    },
     "disableScrollLock": { "description": "Disable the scroll lock behavior." },
     "elevation": { "description": "The elevation of the popover." },
     "marginThreshold": {