Skip to content

[WC-3570]: fix(popup-menu-web): make pop-up menu keyboard accessible - #2447

Merged
r0b1n merged 9 commits into
mainfrom
fix/popup-menu-keyboard-accessibility
Nov 17, 2026
Merged

r0b1n merged 9 commits into
mainfrom
fix/popup-menu-keyboard-accessibility

Conversation

@r0b1n

@r0b1n r0b1n commented Oct 2, 2026 •

Copy link
Copy Markdown
Collaborator

Pull request type

Bug fix (non-breaking change which fixes an issue)


Description

Draft: E2E tests pass locally in Chromium. Still needs Firefox and Safari runs and manual screen reader testing.

The pop-up menu couldn't be used with a keyboard. A Mendix Action Button prevents default on Enter/Space, so Floating UI's useClick ignored the keydown and no native click followed. Menu items weren't focusable at all.

This follows the WAI-ARIA APG Menu Button + Menu pattern. The full design and its rationale are in openspec/changes/fix-popup-menu-keyboard-accessibility/design.md.

  • Trigger: Enter/Space/Arrow Down/Arrow Up open the menu and focus an item. Escape closes it. Our own key handler on the trigger wrapper doesn't depend on the trigger content's defaultPrevented.
  • Menu: role="menu" / menuitem, a roving tabindex via useListNavigation (Up/Down/Home/End, wrap-around), and Enter/Space run the same action as a click. Escape closes the level that contains focus and returns focus.
  • Escape on a Mendix pop-up page: closes only the menu. The Mendix client closes pop-up pages on the Escape keyup, so the menu stops both the keydown and the matching keyup of an Escape it handled. The next Escape still closes the pop-up page.
  • Tab / Shift+Tab: not intercepted. The native tab order already exits the widget. FloatingFocusManager's closeOnFocusOut closes the menu on focus-out. Small onFocus handlers cover the cases Floating UI excuses: focus landing on the trigger, or on a parent item from a submenu. The parent item asks the submenu whether focus came from inside it rather than reading its open state, which updates a render later and missed a fast Shift+Tab.
  • Nested pop-up menus: these act as submenus. Right Arrow/Enter/Space opens one, Left Arrow/Escape closes it, opening a submenu closes its open siblings, and Tab/Shift+Tab close every level.
  • Behavior change: with "Close on: Click outside", an item action that moves focus (e.g. opens a dialog) now closes the menu, for both mouse and keyboard activation.

No XML or property changes.

Tests

  • Unit tests in src/__tests__/PopupMenu.keyboard.spec.tsx.
  • E2E tests in e2e/PopupMenu.keyboard.spec.js, run against the new Keyboard page (/p/keyboard) and KeyboardPopup pop-up page, pushed to the popupmenu-web branch of mendix/testProjects (59b8d3c). They replace the keyboard tests previously added to e2e/PopupMenu.spec.js.
  • The E2E tests wait for the Mendix client's own initial page focus before each test. The client focuses the first focusable element after page load, which otherwise races the test's focus() calls.

What should be covered while testing?

  • A keyboard-only walk of a 2-level menu: open, navigate, open/close a submenu, activate an item (E2E, Chromium).
  • Tab and Shift+Tab from the menu and from a submenu (E2E, Chromium).
  • Tab and Shift+Tab in Firefox and Safari.
  • Escape inside a Mendix pop-up page closes only the menu (E2E, Chromium).
  • Enter/Space on a real Action Button without an action opens the menu (E2E, Chromium).
  • Mouse behavior is unchanged: click to toggle, hover mode, outside click.
  • "Close on: Click outside" plus an item action that opens a dialog: the menu closes (E2E, Chromium, keyboard and mouse).
  • Screen reader announcements (menu, menuitem, expanded state) with VoiceOver and NVDA.
  • Mendix docs: keyboard support section on the Pop-up Menu page (separate docs PR).

@r0b1n
r0b1n force-pushed the fix/popup-menu-keyboard-accessibility branch from 0803c8f to ca6299b Compare October 7, 2026 10:41
@r0b1n
r0b1n marked this pull request as ready for review October 7, 2026 12:43
@r0b1n
r0b1n requested a review from a team as a code owner October 7, 2026 12:43
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@r0b1n r0b1n changed the title fix(popup-menu-web): make pop-up menu keyboard accessible [WC-3570]: fix(popup-menu-web): make pop-up menu keyboard accessible Oct 9, 2026
@github-actions

This comment has been minimized.

@r0b1n
r0b1n force-pushed the fix/popup-menu-keyboard-accessibility branch from da8d3d0 to d5eea75 Compare October 19, 2026 12:35
gjulivan
gjulivan previously approved these changes Oct 29, 2026
@r0b1n
r0b1n force-pushed the fix/popup-menu-keyboard-accessibility branch from d5eea75 to c46af52 Compare November 12, 2026 09:54
@github-actions

This comment has been minimized.

The menu couldn't be opened or navigated from the keyboard: Mendix buttons
prevent default on Enter/Space, so the trigger never opened, and items
weren't focusable. Follows the WAI-ARIA menu button pattern, including
nested menus as submenus.
…ard e2e

- Stop the keyup of an Escape the menu handled. The Mendix client closes
  pop-up pages on the Escape keyup, so a menu on a pop-up page closed the
  page too.
- Close the whole menu on Shift+Tab out of a submenu even when it comes
  right after the submenu opened, by checking whether focus came from
  inside the submenu instead of its re-rendered open state.
- Add keyboard e2e tests for the new Keyboard test page.
- Update the OpenSpec change docs to describe the current behavior only.
…n empty menu

Enter and Space on a text-entry element inside the trigger no longer toggle
the menu, and a click into it opens the menu without moving focus. A menu
without visible items no longer opens, and an empty submenu isn't exposed
on its parent item.
Correct the presentational wording for content inside custom items, document
the text box trigger, empty menu and parent item action behavior, and track
the open findings in tasks.
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

AI Code Review

✅ Approved — no issues found


What was reviewed

File Change
popup-menu-web/src/components/{Menu,MenuItem,PopupMenu,PopupTrigger,PopupContext}.tsx Keyboard support following the WAI-ARIA menu button pattern: menu and menuitem roles, a roving tabindex, submenu open and close, Escape and Tab handling
popup-menu-web/src/hooks/*, src/utils/* usePopup now uses useListNavigation. The new helpers are useTriggerAria, useMouseDownRef, isTextEntry and stopEscapeKeyUp
popup-menu-web/src/__tests__/* New keyboard unit spec and updated snapshots
popup-menu-web/e2e/PopupMenu.keyboard*.spec.js New E2E specs for keyboard, empty menu, text box trigger and dialog focus
popup-menu-web/openspec/** Per-package OpenSpec change (proposal, design, specs, tasks)
popup-menu-web/CHANGELOG.md Two user-facing entries under [Unreleased]

Skipped (out of scope): snapshots beyond a sanity check, lockfiles, dist/

CI: pending: Run automated end-to-end tests, Run code quality check, sigridci · unrelated failures: security/snyk (external scanner; the code and license Snyk checks pass)


Questions

  • The PR description is still marked "Draft" and says Firefox and Safari runs and manual screen reader testing are pending. The checklist marks them done. Please confirm those runs happened before merge.

Positives

  • No XML or property changes, so apps already using the widget keep working. The behavior change (closing the menu when an item action opens a dialog) is documented in the changelog.
  • Focus handling is careful. Tab and Shift+Tab are not intercepted, and onFocus handlers cover the Floating UI gaps. The Escape keyup is stopped so a Mendix pop-up page doesn't close with the menu.
  • The tests cover both unit and E2E levels, with the keyboard E2E specs split by scenario. The changelog entries describe user-visible behavior only.

@r0b1n
r0b1n enabled auto-merge November 17, 2026 12:07
@r0b1n
r0b1n merged commit f7f25a0 into main Nov 17, 2026
13 of 14 checks passed
@r0b1n
r0b1n deleted the fix/popup-menu-keyboard-accessibility branch November 17, 2026 12:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants