[menu] Implement WCAG-compliant focus management for disabled items

[Ch-Valentine]

Summary

Implements proper focus management for disabled menu items according to WCAG accessibility guidelines.

This is related to #1733.

Changes

• MenuRoot: Added disabledIndices state tracking and passed to useListNavigation
• MenuItem: Added logic to register/unregister disabled state in the indices array
• MenuRootContext: Updated interface to include disabled indices management
• Tests: Added comprehensive focus management tests covering:
  • Keyboard opening with disabled first item (WCAG 2.1.1, 2.4.3)
  • Arrow key navigation skipping disabled items (WCAG 2.1.1, 2.4.3)

WCAG Compliance

• WCAG 2.1.1 (Keyboard): All functionality available from keyboard, disabled items properly skipped
• WCAG 2.4.3 (Focus Order): Logical focus order that skips non-focusable disabled items

Testing

• All existing tests pass
• New focus management tests added and passing
• Manual testing confirms proper keyboard navigation behavior

[pkg-pr-new]

vite-css-base-ui-example

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/react@2573

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui-components/utils@2573

commit: ff87fda

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui-components/react	🔺+311B(+0.10%)	🔺+113B(+0.11%)

Details of bundle changes

Generated by 🚫 dangerJS against ff87fda

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	ff87fda
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/68aabe7c1dd5990008eb6a2f
😎 Deploy Preview	https://deploy-preview-2573--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Ch-Valentine]

Demo with a focus management problem BEFORE my changes: https://codesandbox.io/p/sandbox/intelligent-dew-gxwsrp

[atomiks]

@Ch-Valentine the menubar pattern mentions disabled items should be focusable. Screen readers announce them as dimmed, which may be confusing if they're skipped.

In macOS, when using VoiceOver, they don't get skipped; while without VoiceOver, they do. This distinction not being as feasible to check on the web may be why the recommendation always recommends focusing disabled items.

---

As for skipping the first disabled items when first opening, that may be correct regardless, though I am not positive

[Ch-Valentine]

@atomiks thanks for the answer! Hm, that make sense as well) Should I close the PR ?

[atomiks]

@Ch-Valentine it seems it should be skipping the first disabled items when first opening, but still allow them be navigated to with arrow keys afterwards based on the recommendation for menubar items

This issue highlights a somewhat related issue for tabs: #2098

[oliviertassinari]

This discussion reminds me of the disabledItemsFocusable prop in https://mui.com/material-ui/api/menu-list/#menu-list-prop-disabledItemsFocusable. The history: mui/material-ui#19967.

[colmtuite]

I addressed this in Discord recently.

Some stuff from ARIA docs from my Discord post.

"There are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. For example, as demonstrated in the menu and menubar pattern, disabled items are focusable when navigating through a menu with the arrow keys."

https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls
https://www.w3.org/WAI/ARIA/apg/patterns/menubar/#:~:text=Disabled%20menu%20items%20are%20focusable%20but%20cannot%20be%20activated.
https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/#:~:text=Typically%2C%20disabled%20elements%20are%20not%20focusable%20when%20navigating%20with%20a%20keyboard.

I'll close this PR since it would be a mistake. Imo, making it configurable would be a mistake too.

But yes @Ch-Valentine @atomiks it does seem we should be be skipping the first disabled items when first opening. I guess this should be implemented across many components.

[oliviertassinari]

What the other libraries seem to do:

• react-aria. The discussion on this side: Allow disabled menu items to be focused adobe/react-spectrum#1696.
  They went for making disabled menu items not focusable out of concerns that it would lead to so many more Arrow presses for users if they were focusable. For example: https://react-spectrum.adobe.com/react-aria/Menu.html#disabled-items. Instead, they have a different concept to implement disabled items: https://react-spectrum.adobe.com/react-spectrum/Menu.html#unavailable-items. It's not configurable.
• radix. https://www.radix-ui.com/primitives/docs/components/menubar. It behaves like react-aria (disabled menu items are not focusable, but there are no open/closed GitHub issues asking to make them focusable. It's not configurable.
• ariakit. Configurable with the accessibleWhenDisabled prop. Default to not focusable.
• MUI Base. Configurable with the focusableWhenDisabled prop. Default to focusable. The history: [MenuList] Allow including disabled items in keyboard navigation material-ui#19967.

So on those benchmarks, there is a clear skew in favor of not focusable. And on our side, we get user pressure in this same direction, by chronological order:

• [menu] Disabled menu items get highlighted and can even get clicked (sort of) #1733
• https://discord.com/channels/1287292451308048406/1287292451308048409/1405003438395228180
• [menu] Implement WCAG-compliant focus management for disabled items #2573