[Stepper][MenuList][Tabs] Improve accessibility

[silviuaavram]

• I have followed (at least) the PR section of the contributing guide.

Fixes #43689.
Fixes #32826.

Stepper:

• improve markup for stepper and step, from divs to ol and li.
• implement roving tabindex focus for the step buttons.
• step buttons also receive the role of tab, aria-posinset, aria-setsize and aria-selected instead of aria-current.
• stepper that has step buttons will have the role of tablist and aria-orientation
• step that has step buttons will have the role of presentation.

Technical:

• roving tabindex has a separate hook that keeps track of the current focusable item (by index).
• it exports 2 prop getters, one for container, one for item, and a focusNext function
• one source of truth for tabindex values -> the hook.
• update the Tabs and MenuList to also use the hook instead of their own logic
• exported focusNext from the hook, for MenuList to use it for character key focus, in order to keep the single source of truth for the tabindex.
• using refs instead of parsing DOM directly for getting the focusable siblings

UX for roving tabindex:

• tabindex now follows focus. before, it stayed on the selected item, even as you moved away with arrow keys. this created issues:
  • if you tabbed from and back, the previously focused item was forgotten, you would've ended up on the selected item
  • if you moved selection from selected item with arrows, then tabbed / shift tabbed, you could have ended up with the selected item focused, which should not have happened
• this applies to Stepper, Menu / MenuList, Tabs.

[mui-bot]

Netlify deploy preview

• docs/data/material/components/steppers/steppers.md
• docs/data/material/migration/upgrade-to-v9/upgrade-to-v9.md

Bundle size report

Bundle	Parsed size	Gzip size
@mui/material	🔺+1.61KB(+0.31%)	🔺+678B(+0.45%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	🔺+1.94KB(+15.10%)	🔺+761B(+15.11%)

Details of bundle changes

Generated by 🚫 dangerJS against 43d0bf6

[Copilot]

Pull request overview

This pull request improves the accessibility of the Stepper component by implementing semantic HTML markup and keyboard navigation following ARIA best practices.

Changes:

• Replaced div elements with semantic ol/li elements for Stepper and Step components
• Implemented roving tabindex focus management with arrow key navigation for step buttons
• Added ARIA attributes (aria-posinset, aria-setsize, aria-orientation) to improve screen reader support
• Refactored StepperContext to export only useStepperContext hook and StepperContextProvider, removing the default export

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.ts	New hook implementing circular keyboard navigation with arrow keys, skipping disabled steps
packages/mui-material/src/Stepper/utils/useRovingTabIndexFocus.test.tsx	Comprehensive unit tests for the roving tabindex hook
packages/mui-material/src/Stepper/index.js	Removed default export of StepperContext, keeping named exports
packages/mui-material/src/Stepper/index.d.ts	Updated TypeScript exports to match JavaScript changes
packages/mui-material/src/Stepper/StepperContext.ts	Added new context properties for focus management, marked as @internal, exported StepperContextProvider
packages/mui-material/src/Stepper/Stepper.test.tsx	Updated test to expect HTMLOListElement instead of HTMLDivElement
packages/mui-material/src/Stepper/Stepper.js	Changed root element from div to ol, integrated roving tabindex, added aria-orientation
packages/mui-material/src/StepLabel/StepLabel.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepContent/StepContent.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepConnector/StepConnector.js	Updated to use useStepperContext hook instead of direct context import
packages/mui-material/src/StepButton/StepButton.test.js	Added StepperContextProvider wrapper to all test cases
packages/mui-material/src/StepButton/StepButton.js	Integrated roving tabindex, added ARIA attributes, implemented keyboard and click handlers
packages/mui-material/src/StepButton/StepButton.d.ts	Added TypeScript definitions for onClick and onKeyDown props
packages/mui-material/src/Step/Step.test.js	Updated tests for li element and added StepperContextProvider wrappers
packages/mui-material/src/Step/Step.js	Changed root element from div to li, updated to use useStepperContext hook

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ZeeshanTamboli]

@silviuaavram Tested it initially with NVDA screen reader. Nice improvements.

1. With NVDA enabled, the Left/Right arrow keys don't work on the non-linear stepper:
   https://deploy-preview-47687--material-ui.netlify.app/material-ui/react-stepper/#non-linear and nothing is announced as well. When NVDA is off, arrow-key navigation works as expected.
2. Is it expected that Tab key should move focus to the next step? Since this isn't a tablist, I'm not sure. On the docs site (https://mui.com/material-ui/react-stepper/#non-linear), Tab moves between steps, but in this PR it jumps directly to the "Next" button.
3. If useStepperContext is intended to be a public API, I think we should document how to use it with a custom stepper demo.

[silviuaavram]

Hey @ZeeshanTamboli thanks for your input!

1. I don't know what to say, especially that I don't have a windows setup at the moment. For example, does this stepper work with NVDA?
2. I expect Tab to only work on one step at a time. Focusing other steppers with keyboard should work with arrows instead.
3. useStepperContext should not be public, as StepperContext wasn't public either, right? The hook is meant be used internally, instead of doing useContext(StepperContext).

[ZeeshanTamboli]

Hey @ZeeshanTamboli thanks for your input!

1. I don't know what to say, especially that I don't have a windows setup at the moment. For example, does this stepper work with NVDA?

Yes, it works. I am able to navigate with left/right arrow keys with NVDA enabled in this demo but not in this PR's demo.

2. I expect Tab to only work on one step at a time. Focusing other steppers with keyboard should work with arrows instead.

Ok, so you mean, pressing Tab should focus only on the last focused step in the Stepper and not move to the next step like in production?

3. useStepperContext should not be public, as StepperContext wasn't public either, right? The hook is meant be used internally, instead of doing useContext(StepperContext).

I read this only export useStepperContext in order to control the usage better. in the PR description, so I thought it is exported.

[ArmandRedgate]

Hey,

This probably isn't the best place to say this, but this work has caused some failures in our accessibility scanning because the StepConnectors are div children to the ol stepper, and those are not allowed.

One way to fix this is to set aria-hidden="true" on those StepConnectors. Any chance you could do that or something like it? Consumers of MUI cannot do this I think because of no slotProps for the connector, at least none that I could find.

Thanks.

[mj12albert]

@ArmandRedgate Would you mind opening a new issue 🙏

[ArmandRedgate]

@mj12albert you know what?

If that's alright I'll try making this fix my first open source contribution. Embarrassing given I've been coding professionally for over 5 years. I'll make a PR.

[oliviertassinari]

It's more of an issue with having a correct HTML structure, than a11y; no?

https://validator.w3.org/nu/?doc=https%3A%2F%2Fdeploy-preview-48397--material-ui.netlify.app%2Fmaterial-ui%2Freact-stepper%2F

[ArmandRedgate]

It's more of an issue with having a correct HTML structure, than a11y; no?

Yes, but the only alternative I can think of to hiding them is to make them list items, and you should not do that as they are not part of the list. They are for visual display purposes only.

[ArmandRedgate]

I forgot to link the completed PR, here you go: #48397