An open source design system that's fully customizable and agent ready
TypeScript
fix(DropdownMenu, ContextMenu): Tab from any sub-menu level closes the whole menu (#8870)
Cindy Zhang70597367fa7b
diff --git a/.changeset/submenu-tab-closes-menu.md b/.changeset/submenu-tab-closes-menu.mdnew file mode 100644index 0000000000..3c8c4b2e7b--- /dev/null+++ b/.changeset/submenu-tab-closes-menu.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] `DropdownMenu`, `ContextMenu` and `BreadcrumbItem` menus without a `header` or `footer`: Tab or Shift+Tab on a row inside an open sub-menu flyout now closes every open level and the menu, calls `onOpenChange(false)` once, and lets focus move on from the trigger, as Tab already did from a top-level row (WAI-ARIA Menu Button). Before, the menu stayed open. A menu or sub-menu with a `header` or `footer` keeps its Tab cycle.++@cixzhangdiff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.mdindex 2827317964..9fa7503274 100644--- a/docs/specs/components/ContextMenu/ContextMenu.spec.md+++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md@@ -112,6 +112,7 @@ Consumer props, content modes, and presentation policy remain documented in| FR8 | In the pointer menu ArrowDown on the last row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp page as in `component:DropdownMenu` FR12; a held key's auto-repeat does not activate; typeahead matches the row's label element alone. A disabled row is reached by these keys and by typeahead and stays inert, as `component:DropdownMenu` FR17 states. Implementation gap: the arrow keys and typeahead skip disabled rows today (Current-state impact). | Current source and tests || FR9 | While the Pointer menu surface is open, it participates in `family:overlay-dismissal` through the shared stack and provides descendant depth. One Escape press affects only the top-most present nested surface; ContextMenu closes only when it is that surface. | `family:overlay-dismissal` FR1–FR6; `ContextMenu.test.tsx` nested-layer case || FR10 | ContextMenu MUST be built on the public headless context menu (`spec:AST-107` FR8), with its invocation, open state, and cleanup the factory's and no behavior of its own beside the factory's. Implementation gap: no headless context menu ships; ContextMenu owns its invocation, open state, outside-press listener, and cleanup itself. | `spec:AST-107` FR8 |+| FR11 | Tab or Shift+Tab on a row of the pointer menu, its own or an open sub-menu flyout's at any depth, closes every open level and the menu and calls `onOpenChange(false)` once, as `component:DropdownMenu` FR23 states for its menu. | WAI-ARIA Menu Button pattern; current tests |### Allowed variation@@ -243,23 +244,24 @@ anchor is positioning infrastructure rather than consumer anatomy.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |-| FR1, FR4 | `ContextMenu.test.tsx` rendering, invocation, bottom-sheet, adaptive, compound, and disabled cases ("renders menu with role=\"menu\"", "opens menu on right-click", "opens from a keyboard-invoked contextmenu (Shift+F10 / Menu key)", "opens on touch long-press", "opens the real menu content in a BottomSheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "renders menuContent as menu items", "does not open when isDisabled is true") | Right-click, keyboard, long press; pointer and sheet; data and compound; disabled | A missing invocation path, menu role, sheet, or compound interior, or a disabled trigger that opens, fails. Evidence gap: no test asserts that a disabled trigger leaves the native context menu alone. | `audit:ContextMenu/anatomy` |-| FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts `context-menu` on either painted surface or its absence from the trigger. | `audit:ContextMenu/theming` |-| FR3 | `ContextMenu.test.tsx` destructive-variant, section, divider, selectable, and alias cases | Shared rows through ContextMenu | A row that loses DropdownMenu's semantics or variant fails. Evidence gap: no test asserts the BottomSheet and List delegation beyond rendering. | `audit:ContextMenu/theming` |-| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and scroll outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, or a tap or mouse press outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift; the scroll-outside and pen cases assert the current gaps. | `audit:ContextMenu/behavior` |-| FR5, DD1 touch scope | Browser tests on the touch story, the menu opened by a finger under a coarse pointer and by a mouse and by Shift+F10 under a fine pointer | Touch-opened, mouse-opened and keyboard-opened menus on a block trigger | A mouse- or keyboard-opened menu that lifts its trigger, tints the page or grows, or a touch-opened menu that blurs the page, grows a second surface, or animates anything but transform and opacity, fails. Evidence gap: the lift and the grow are unbuilt, so no test asserts either. | `audit:ContextMenu/behavior` |-| FR5 Reduce Motion | Browser tests on the touch story with reduced motion | A touch-opened menu opening and closing under Reduce Motion | A lift, grow or shrink that moves rather than playing an opacity-only cross-fade of 200 ms or less (`spec:AST-094` FR8) fails. Evidence gap: no test exists. | `audit:ContextMenu/behavior` |-| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a curve or a literal instead of its spring role, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` |-| DEC-2 | Element-count browser test on the touch story (`spec:AST-017` FR60) | At rest and lifted, fine and coarse pointer | A lift element at rest, a copy of the trigger, or an open count beyond the layer, the shadow, the anchor and the placeholder fails. Evidence gap: the lift is unbuilt, so no test exists. | `audit:ContextMenu/anatomy` |-| FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` |-| FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` |-| FR8 | `ContextMenu.test.tsx` "wraps arrow navigation at the ends", typeahead cases, and disabled-row keyboard cases (`component:DropdownMenu` FR17) | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, a disabled row the keys or typeahead skip, or a disabled row that acts or closes the menu fails. Evidence gap: no test asserts Page keys or auto-repeat. | `audit:ContextMenu/behavior` |-| FR9 | `ContextMenu.test.tsx` "lets a nested layer consume Escape before the context menu", "closes on Escape even when opened without auto-focus", and "ignores Escape during IME composition" | Nested layer; Escape; composition | A context menu that closes with its nested child, or on a composition Escape, fails. | `audit:ContextMenu/behavior` |-| FR10, PR1 | `ContextMenu.test.tsx` invocation and handler-composition cases ("composes the consumer context-menu handler with menu opening", "keeps component-owned opening when a consumer prevents default", "composes consumer touch handlers with long-press detection") | Right click, long press, keyboard | A context request that does not open the menu, or a dropped consumer handler, fails. Evidence gap: no test asserts listener cleanup on unmount; nothing tests a headless factory, which does not ship (the FR10 gap). | `audit:ContextMenu/behavior` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` |-| RTL relation | RTL audit curated D2 target (`apps/storybook/rtl-audit/targets.json`) on the `Presentation / BottomSheet submenu` story | BottomSheet opened into a submenu, LTR and RTL | The sheet header's back button not at the inline start of its heading in both directions fails D2. | `audit:ContextMenu/i18n-rtl` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |+| FR1, FR4 | `ContextMenu.test.tsx` rendering, invocation, bottom-sheet, adaptive, compound, and disabled cases ("renders menu with role=\"menu\"", "opens menu on right-click", "opens from a keyboard-invoked contextmenu (Shift+F10 / Menu key)", "opens on touch long-press", "opens the real menu content in a BottomSheet when requested", "uses the BottomSheet for adaptive presentation on compact touch", "renders menuContent as menu items", "does not open when isDisabled is true") | Right-click, keyboard, long press; pointer and sheet; data and compound; disabled | A missing invocation path, menu role, sheet, or compound interior, or a disabled trigger that opens, fails. Evidence gap: no test asserts that a disabled trigger leaves the native context menu alone. | `audit:ContextMenu/anatomy` |+| FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts `context-menu` on either painted surface or its absence from the trigger. | `audit:ContextMenu/theming` |+| FR3 | `ContextMenu.test.tsx` destructive-variant, section, divider, selectable, and alias cases | Shared rows through ContextMenu | A row that loses DropdownMenu's semantics or variant fails. Evidence gap: no test asserts the BottomSheet and List delegation beyond rendering. | `audit:ContextMenu/theming` |+| FR5 | `ContextMenu.test.tsx` "acts on the row under a finger release, once, and swallows the stray click" and outside-dismissal cases; `ContextMenuLongPress.a11y.chromium.spec.ts` | Finger release; long press lift; tap, mouse, pen, and scroll outside | A row acting on the press row, a stray click that acts, a long press that closes its own menu, or a tap or mouse press outside that leaves it open fails. Evidence gap: no test asserts the FR31 grow, the opening-finger handoff, or the FR33 lift; the scroll-outside and pen cases assert the current gaps. | `audit:ContextMenu/behavior` |+| FR5, DD1 touch scope | Browser tests on the touch story, the menu opened by a finger under a coarse pointer and by a mouse and by Shift+F10 under a fine pointer | Touch-opened, mouse-opened and keyboard-opened menus on a block trigger | A mouse- or keyboard-opened menu that lifts its trigger, tints the page or grows, or a touch-opened menu that blurs the page, grows a second surface, or animates anything but transform and opacity, fails. Evidence gap: the lift and the grow are unbuilt, so no test asserts either. | `audit:ContextMenu/behavior` |+| FR5 Reduce Motion | Browser tests on the touch story with reduced motion | A touch-opened menu opening and closing under Reduce Motion | A lift, grow or shrink that moves rather than playing an opacity-only cross-fade of 200 ms or less (`spec:AST-094` FR8) fails. Evidence gap: no test exists. | `audit:ContextMenu/behavior` |+| FR5 motion roles | Role registry tests over `spec:AST-094` FR4 | `springs.contextMenuLift`, `springs.contextMenuDismiss` and `springs.contextMenuMorph` at tempo 1 and `'standard'` | A lift, return or grow that plays a curve or a literal instead of its spring role, or a role off its FR4 table value, fails. | `audit:ContextMenu/behavior` |+| DEC-2 | Element-count browser test on the touch story (`spec:AST-017` FR60) | At rest and lifted, fine and coarse pointer | A lift element at rest, a copy of the trigger, or an open count beyond the layer, the shadow, the anchor and the placeholder fails. Evidence gap: the lift is unbuilt, so no test exists. | `audit:ContextMenu/anatomy` |+| FR6, AR1, ORD1 | `ContextMenu.test.tsx` "inline trigger (triggerAs)" and cursor-anchor cases; "does not put aria-haspopup on the role-less trigger wrapper (menus-15)"; `ContextMenu.triggerProps.test.tsx`; `ContextMenuCursorAnchor.a11y.browser.spec.ts` | `span` in a paragraph; default `div`; pointer and keyboard anchors | A block trigger in prose, a trigger with a role or `aria-haspopup`, or an anchor outside the trigger fails. | `audit:ContextMenu/behavior` |+| FR7 | `ContextMenu.test.tsx` "drills into nested data items inside the BottomSheet", "renders a submenu from a nested items array and keyboard-reaches an item after it", and "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Sheet drill-in; pointer sub-menu; regions under ContextMenu | A missing sub-menu, an unreachable row after it, or a sub-menu dialog under ContextMenu fails. Evidence gap: no test here asserts the pointer drill-in on a phone. | `audit:ContextMenu/behavior` |+| FR8 | `ContextMenu.test.tsx` "wraps arrow navigation at the ends", typeahead cases, and disabled-row keyboard cases (`component:DropdownMenu` FR17) | Wrap; typeahead; disabled rows | A clamped arrow, a missing typeahead match, a disabled row the keys or typeahead skip, or a disabled row that acts or closes the menu fails. Evidence gap: no test asserts Page keys or auto-repeat. | `audit:ContextMenu/behavior` |+| FR9 | `ContextMenu.test.tsx` "lets a nested layer consume Escape before the context menu", "closes on Escape even when opened without auto-focus", and "ignores Escape during IME composition" | Nested layer; Escape; composition | A context menu that closes with its nested child, or on a composition Escape, fails. | `audit:ContextMenu/behavior` |+| FR10, PR1 | `ContextMenu.test.tsx` invocation and handler-composition cases ("composes the consumer context-menu handler with menu opening", "keeps component-owned opening when a consumer prevents default", "composes consumer touch handlers with long-press detection") | Right click, long press, keyboard | A context request that does not open the menu, or a dropped consumer handler, fails. Evidence gap: no test asserts listener cleanup on unmount; nothing tests a headless factory, which does not ship (the FR10 gap). | `audit:ContextMenu/behavior` |+| FR11 | `ContextMenu.test.tsx` "Tab from a flyout leaves the whole menu" case | a sub-menu row | A Tab that leaves the menu or a flyout open, or a second `onOpenChange(false)`, fails. | `audit:ContextMenu/accessibility` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:ContextMenu/theming` |+| RTL relation | RTL audit curated D2 target (`apps/storybook/rtl-audit/targets.json`) on the `Presentation / BottomSheet submenu` story | BottomSheet opened into a submenu, LTR and RTL | The sheet header's back button not at the inline start of its heading in both directions fails D2. | `audit:ContextMenu/i18n-rtl` |## Current-state impactdiff --git a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenu.spec.mdindex ddd08f503a..866251e6dc 100644--- a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md@@ -144,6 +144,7 @@ component-local concepts; each keeps its released default.| FR20 | With `header` or `footer` on a sub-menu (`DropdownMenuSubMenu`), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's `role="menu"` (rows only), then the footer. It sits in a host `DropdownMenu` renders beside its menu, never inside a menu; under a root with no such host (`ContextMenu`) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes. | Current behavior; FR15; AR5 || FR21 | Under a finger, in the touch modes (`presentation` not pinned to `'popover'`), the pointer menu MUST grow out of the Trigger button on the theme's entrance duration and easing tokens and collapse back into it on the theme's exit duration and easing (`spec:AST-094` FR7, FR31, FR45), and MUST close as a pan that starts outside it begins (FR32); a pinned `'popover'` keeps the layer's own entrance. A pan dismissal is the menu's own close: focus that was in the menu returns to the Trigger button, whose `aria-expanded` turns false. A mouse keeps the layer's own entrance and exit. Implementation gap: the menu keeps the layer's own entrance and exit under a finger too, and has no pan-outside dismissal of its own. | `spec:AST-094` FR31, FR32; `family:overlay-dismissal` AV6 || FR22 | Under a finger, in the touch modes, where the primary pointer is coarse (a phone or a tablet), a tap or a drag that lands while the pointer menu enters MUST reach nothing: it closes nothing, scrolls nothing, moves no focus and clicks nothing (`spec:AST-094` FR35). The finger that opened the menu still picks the row it lifts on (FR8). Keys and assistive technology stay live. A mouse, a pinned `'popover'` and a finger where the primary pointer is fine (a touchscreen laptop) hold nothing, as for `component:Drawer`. Implementation gap: after a finger, a still mouse's first press lands on the entering menu's shield and does nothing (`spec:AST-094` FR35). | `spec:AST-094` FR35; `architecture:layer-runtime` |+| FR23 | Tab or Shift+Tab on a row at any level of a menu without `header` or `footer`, its own rows or an open sub-menu flyout's at any depth, closes every open level and the menu, calls `onOpenChange(false)` once, and leaves focus to move on from the trigger in page order (WAI-ARIA Menu Button). A level with a header or footer keeps FR15's and FR20's Tab cycle within it. | WAI-ARIA Menu Button pattern; current tests |### Allowed variation@@ -363,6 +364,7 @@ than adding a DropdownMenu-owned heading target.| FR20, AR7 | `DropdownMenuSubMenu.test.tsx` header and footer cases, including "on a phone"; `SubMenuHeaderFooter.a11y.chromium.spec.ts`; `ContextMenu.test.tsx` "shows a sub-menu with a header or footer as its rows alone, and says why in development" | Fine pointer and phone; Escape paths; nested flyouts; pointer leaving | A region inside a menu, an unnamed dialog, a Tab walk that does not wrap, an Escape that closes the root, or a flyout that closes while focus is inside fails. | `audit:DropdownMenu/accessibility` || FR21 | Evidence gap: no test, matching the FR21 gap | — | — | `audit:DropdownMenu/behavior` || FR22 | `DropdownMenu.test.tsx` "DropdownMenu entrance under a finger" cases; `useMenuPress.test.tsx` "an input hold over the menu" cases; `DropdownMenuEntranceHold.interaction.browser.spec.ts` | A tap outside and a finger's slide while the menu enters; a mouse click | A tap during the entrance that closes the menu, clicks the page or moves focus, a slide that picks nothing, or a held mouse fails. | `audit:DropdownMenu/behavior` |+| FR23 | `DropdownMenu.test.tsx` Tab cases; `DropdownMenuSubMenu.test.tsx` "Tab from a flyout leaves the whole menu" suite | top level, one and two levels down, Shift+Tab | A Tab that leaves any level open, a second `onOpenChange(false)`, or a prevented Tab fails. | `audit:DropdownMenu/accessibility` || PR1 | Evidence gap: no test asserts the listener and observer bounds | — | — | `audit:DropdownMenu/behavior` || Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:DropdownMenu/theming` |diff --git a/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.mdindex a5a13d6407..0a8bf0a361 100644--- a/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md@@ -108,17 +108,18 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |-| FR1 | The row exposes `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface is labelled by the row. | `spec:AST-020`; current source and tests |-| FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) opens the surface; a keyboard open focuses its first enabled row. Escape or the close arrow closes only this level and returns focus to the row. A hover opens a flyout after an intent delay. | `spec:AST-020`; `architecture:interaction-modality`; current tests |-| FR3 | A flyout sits beside the row on the inline-end side, flips with direction, and stays within the viewport; its block size caps at the smaller of its own cap and the viewport. | `architecture:layer-runtime`; current source |-| FR4 | A drilled-in view replaces the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow return to the row. | Current source and focused tests |-| FR5 | Selecting a leaf row inside the surface closes every level and the root menu. | Current source and tests |-| FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change. Implementation gap: a drilled-in view reset by the root menu closing reports no `false` (OQ1). | Documented promise; `architecture:react-component-runtime` INV2 |-| FR7 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), takes no hover focus, opens on no input, and runs no caller `onClick`. Implementation gap: a disabled row renders no `tabindex` today. | Current source and tests |-| FR8 | With `hasSpinner` the row shows a decorative spinner in place of the caret and announces the busy start once the root menu shows. | `spec:AST-086` FR8; current source and tests |-| FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler. | `architecture:public-component-api` INV5–INV8; current tests |+| ID | Invariant | Basis |+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |+| FR1 | The row exposes `role="menuitem"`, `aria-haspopup="menu"` (`"dialog"` with a header or footer), `aria-expanded` matching its surface, and `aria-controls` naming the surface while open. The surface is labelled by the row. | `spec:AST-020`; current source and tests |+| FR2 | A click, Enter, Space, or the inline-end arrow (inline-start under RTL) opens the surface; a keyboard open focuses its first enabled row. Escape or the close arrow closes only this level and returns focus to the row. A hover opens a flyout after an intent delay. | `spec:AST-020`; `architecture:interaction-modality`; current tests |+| FR3 | A flyout sits beside the row on the inline-end side, flips with direction, and stays within the viewport; its block size caps at the smaller of its own cap and the viewport. | `architecture:layer-runtime`; current source |+| FR4 | A drilled-in view replaces the root's rows with a Back row named after the parent menu and then this row's children; Back, Escape, and the close arrow return to the row. | Current source and focused tests |+| FR5 | Selecting a leaf row inside the surface closes every level and the root menu. | Current source and tests |+| FR6 | `onOpenChange` MUST report `true` once when the surface opens and `false` once when it closes, from the action that caused the change. Implementation gap: a drilled-in view reset by the root menu closing reports no `false` (OQ1). | Documented promise; `architecture:react-component-runtime` INV2 |+| FR7 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), takes no hover focus, opens on no input, and runs no caller `onClick`. Implementation gap: a disabled row renders no `tabindex` today. | Current source and tests |+| FR8 | With `hasSpinner` the row shows a decorative spinner in place of the caret and announces the busy start once the root menu shows. | `spec:AST-086` FR8; current source and tests |+| FR9 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root after the row's own behavior; the open keys and a disabled click stop before the caller's handler. | `architecture:public-component-api` INV5–INV8; current tests |+| FR10 | Without its own `header` or `footer` and with none on a level above it, Tab or Shift+Tab on a row in the flyout closes this level as the key bubbles to the menu, which closes the whole menu (`component:DropdownMenu` FR23, `component:ContextMenu` FR11). | WAI-ARIA Menu Button pattern; current tests |### Allowed variation@@ -201,6 +202,7 @@ No component-local visual decision is recorded.| FR4 | `DropdownMenuSubMenu.test.tsx` drill-in cases; `DropdownMenuDrillIn.a11y.chromium.spec.ts` | Drilled view; Back | A missing Back row or a Back that does not return fails. | `audit:DropdownMenuSubMenu/behavior` || FR5 | `DropdownMenuSubMenu.test.tsx` "closes the whole menu after selecting a nested item" and "activates a nested item with the Enter key and closes the menu" | Pointer and Enter | A level left open after a leaf pick fails. | `audit:DropdownMenuSubMenu/behavior` || FR6 | `DropdownMenuSubMenu.test.tsx` "reports each flyout open and close to onOpenChange once" | Flyout open and close | A missing or repeated report fails. Evidence gap: the drill-in reset gap is not asserted. | `audit:DropdownMenuSubMenu/behavior` |+| FR10 | `DropdownMenuSubMenu.test.tsx` "Tab from a flyout leaves the whole menu" suite; `ContextMenu.test.tsx` matching case | one and two levels down, Shift+Tab | A flyout left open after Tab fails. | `audit:DropdownMenuSubMenu/accessibility` || FR7, FR9 | `DropdownMenuSubMenu.test.tsx` "does not open a disabled submenu", "a disabled row does not pass a click on to the caller's onClick", host-attribute and ref cases ("aria-\*, data-\* and id reach the trigger row, and the flyout stays labelled by it", "a ref reaches the trigger row", "a caller's handlers run after the row's own, and the row still opens and takes the hover focus") | Disabled; caller handlers and attributes | A disabled open or caller click, or a dropped attribute, ref, or handler, fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the row, a disabled row's `tabindex="-1"`, or that the parent's keyboard reaches it (`component:DropdownMenu` FR17). | `audit:DropdownMenuSubMenu/api` || FR8 | `BusyOwnerAnnouncement.test.tsx` "DropdownMenuSubMenu loading state" cases; `DropdownMenuSubMenu.test.tsx` loading-flyout cases | Loading closed and open | A busy start announced while closed, twice, or not at all, or an announced Spinner, fails. | `audit:DropdownMenuSubMenu/accessibility` || AR4, PR1 | `DropdownMenuForcedColors.test.tsx` (the row's `:focus-visible` ring and token inset); `DropdownMenuAudit.a11y.chromium.spec.ts` forced-colors frames. Evidence gap: no test asserts the timer bounds | — | — | `audit:DropdownMenuSubMenu/visual` |diff --git a/packages/cli/api/component/__fixtures__/resolutions/modules.txt b/packages/cli/api/component/__fixtures__/resolutions/modules.txtindex f13fef799e..026da20cc5 100644--- a/packages/cli/api/component/__fixtures__/resolutions/modules.txt+++ b/packages/cli/api/component/__fixtures__/resolutions/modules.txt@@ -168,7 +168,6 @@ menuPressGesture menuPressGesture hooks/useAnimatedLayout.doc.mjs hooks/menuPresmenuPressMarker menuPressMarker hooks/useAnimatedLayout.doc.mjs hooks/menuPressMarker.tsmenuPressOnItems menuPressOnItems hooks/useAnimatedLayout.doc.mjs hooks/menuPressOnItems.tsmenuRegionStops menuRegionStops DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/menuRegionStops.ts-menuRegionsContext menuRegionsContext DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/menuRegionsContext.tsmenuWidth menuWidth DropdownMenu/DropdownMenu.doc.mjs DropdownMenu/menuWidth.tsmergeComponents mergeComponents theme/MediaTheme.doc.mjs theme/mergeComponents.tsmodalAnnounce modalAnnounce hooks/useAnimatedLayout.doc.mjs hooks/modalAnnounce.tsdiff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsxindex a959058ba9..222f44ddf6 100644--- a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx+++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx@@ -598,7 +598,12 @@ function BreadcrumbMenuTrigger({(e: React.KeyboardEvent) => {// A submenu flyout renders inline inside this menu; its key events bubble// up here. Let that level own them — only handle events from this level.+ // Except Tab: each open flyout has closed itself as the key bubbled up,+ // and the menu closes as Tab from one of its own rows would (APG).if (!ownsEvent(e)) {+ if (e.key === 'Tab') {+ closeMenu();+ }return;}if (e.key === 'Enter' || e.key === ' ') {diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsxindex c1770d1737..969a6aa5d6 100644--- a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx@@ -912,6 +912,53 @@ describe('BreadcrumbItem menu', () => {).toHaveFocus();});+ it('closes the whole breadcrumb menu on Tab from a submenu flyout row', async () => {+ render(+ <Breadcrumbs>+ <BreadcrumbItem+ menu={[+ {label: 'Rename', onClick: vi.fn()},+ {+ label: 'Move to',+ items: [+ {label: 'Folder A', onClick: vi.fn()},+ {label: 'Folder B', onClick: vi.fn()},+ ],+ },+ ]}>+ Teams+ </BreadcrumbItem>+ <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>+ </Breadcrumbs>,+ );+ const trigger = screen.getByRole('button', {name: 'Teams'});+ trigger.focus();+ fireEvent.keyDown(trigger, {key: 'ArrowDown'});+ const submenuTrigger = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });+ await waitFor(() => {+ expect(+ screen.getByRole('menuitem', {name: 'Rename', hidden: true}),+ ).toHaveFocus();+ });+ act(() => submenuTrigger.focus());+ fireEvent.keyDown(submenuTrigger, {key: 'ArrowRight'});+ const folderA = await screen.findByRole('menuitem', {+ name: 'Folder A',+ hidden: true,+ });+ await waitFor(() => expect(folderA).toHaveFocus());++ fireEvent.keyDown(folderA, {key: 'Tab'});++ await waitFor(() =>+ expect(trigger).toHaveAttribute('aria-expanded', 'false'),+ );+ expect(submenuTrigger).toHaveAttribute('aria-expanded', 'false');+ });+it('allows menu together with isCurrent (both aria-current and aria-haspopup)', () => {render(<Breadcrumbs>diff --git a/packages/core/src/ContextMenu/ContextMenu.test.tsx b/packages/core/src/ContextMenu/ContextMenu.test.tsxindex 3d321df7fb..d68f7a78dc 100644--- a/packages/core/src/ContextMenu/ContextMenu.test.tsx+++ b/packages/core/src/ContextMenu/ContextMenu.test.tsx@@ -1770,3 +1770,47 @@ describe('ContextMenu outside dismissal', () => {expect(onOpenChange).not.toHaveBeenCalledWith(false);});});++describe('ContextMenu: Tab from a flyout leaves the whole menu (APG menu button)', () => {+ it('Tab on a sub-menu row closes every level, once', async () => {+ const onOpenChange = vi.fn();+ render(+ <ContextMenu+ onOpenChange={onOpenChange}+ items={[+ {label: 'Cut', onClick: () => {}},+ {+ label: 'Move to',+ items: [+ {label: 'Folder A', onClick: () => {}},+ {label: 'Folder B', onClick: () => {}},+ ],+ },+ ]}>+ <div>Right-click me</div>+ </ContextMenu>,+ );+ fireEvent.contextMenu(screen.getByText('Right-click me'));+ const menu = screen.getAllByRole('menu', {hidden: true})[0];+ const moveTo = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });+ fireEvent.click(moveTo, {detail: 1});+ await waitFor(() =>+ expect(moveTo).toHaveAttribute('aria-expanded', 'true'),+ );+ const folder = screen.getByRole('menuitem', {+ name: 'Folder A',+ hidden: true,+ });+ act(() => folder.focus());+ onOpenChange.mockClear();+ const tab = fireEvent.keyDown(folder, {key: 'Tab'});+ expect(tab).toBe(true);+ expect(moveTo).toHaveAttribute('aria-expanded', 'false');+ expect(menu.closest('[popover]')).not.toHaveAttribute('popover-open');+ expect(onOpenChange).toHaveBeenCalledTimes(1);+ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+});diff --git a/packages/core/src/ContextMenu/ContextMenu.tsx b/packages/core/src/ContextMenu/ContextMenu.tsxindex 7dc0e23dcb..b3b1536ec9 100644--- a/packages/core/src/ContextMenu/ContextMenu.tsx+++ b/packages/core/src/ContextMenu/ContextMenu.tsx@@ -554,7 +554,12 @@ export function ContextMenu({(e: React.KeyboardEvent) => {// A submenu flyout renders inline inside this menu; its key events bubble// up here. Let that level own them — only handle events from this level.+ // Except Tab: each open flyout has closed itself as the key bubbled up,+ // and the menu closes as Tab from one of its own rows would (APG).if (!ownsEvent(e)) {+ if (e.key === 'Tab') {+ closeMenu();+ }return;}if (e.key === 'Enter' || e.key === ' ') {diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsxindex b7fea7a022..31ea12aa27 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx@@ -79,7 +79,6 @@ import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';import {returnFocusForLastInput} from '../utils/focusReturn';import {PressGroupContext} from '../hooks/pressGroupContext';import {useMenuOverflow} from './useMenuOverflow';-import {MenuRegionsContext} from './menuRegionsContext';import {moveRegionsTab} from './menuRegionStops';import {useDevWarning} from '../hooks/useDevWarning';import {useMenuDrillIn} from './useMenuDrillIn';@@ -1258,11 +1257,16 @@ function DropdownMenuPopover({// A submenu flyout renders inline inside this menu; its key events bubble// up here. Let that level own them — only handle events from this level.if (!ownsEvent(e)) {- // Except Tab with a header or footer: each open flyout has closed- // itself as the key bubbled up, and the root moves focus on as Tab- // from one of its own rows would.- if (e.key === 'Tab' && hasRegions) {- moveDialogTab(e, true);+ // Except Tab: each open flyout has closed itself as the key bubbled+ // up, and the root moves on as Tab from one of its own rows would.+ // With a header or footer that walks the regions; otherwise the menu+ // closes and focus moves on from the trigger (APG menu button).+ if (e.key === 'Tab') {+ if (hasRegions) {+ moveDialogTab(e, true);+ } else {+ closeMenu();+ }}return;}@@ -1765,15 +1769,13 @@ function DropdownMenuPopover({className,style,)}>- <MenuRegionsContext value={hasRegions}>- <DropdownMenuContext value={contextValue}>- <DropdownMenuSurfaceContext value={surfaceValue}>- <DropdownMenuRootOpenContext value={isOpen}>- {menuContent}- </DropdownMenuRootOpenContext>- </DropdownMenuSurfaceContext>- </DropdownMenuContext>- </MenuRegionsContext>+ <DropdownMenuContext value={contextValue}>+ <DropdownMenuSurfaceContext value={surfaceValue}>+ <DropdownMenuRootOpenContext value={isOpen}>+ {menuContent}+ </DropdownMenuRootOpenContext>+ </DropdownMenuSurfaceContext>+ </DropdownMenuContext></div>,),{diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsxindex ab6f0be0ff..9a23665bb8 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx@@ -2440,3 +2440,78 @@ describe('DropdownMenuSubMenu header and footer', () => {});});});++describe('DropdownMenuSubMenu: Tab from a flyout leaves the whole menu (APG menu button)', () => {+ function TabMenu({onOpenChange}: {onOpenChange: (open: boolean) => void}) {+ return (+ <>+ <DropdownMenu button={{label: 'File'}} onOpenChange={onOpenChange}>+ <DropdownMenuItem label="Open" onClick={() => {}} />+ <DropdownMenuSubMenu label="Export">+ <DropdownMenuItem label="PDF" onClick={() => {}} />+ <DropdownMenuSubMenu label="Image">+ <DropdownMenuItem label="PNG" onClick={() => {}} />+ <DropdownMenuItem label="JPEG" onClick={() => {}} />+ </DropdownMenuSubMenu>+ </DropdownMenuSubMenu>+ </DropdownMenu>+ <button type="button">After</button>+ </>+ );+ }++ const row = (name: string | RegExp) =>+ screen.getByRole('menuitem', {name, hidden: true});++ async function openExport(onOpenChange: (open: boolean) => void) {+ const user = userEvent.setup();+ render(<TabMenu onOpenChange={onOpenChange} />);+ const trigger = screen.getByRole('button', {name: /File/});+ await user.click(trigger);+ const menu = screen.getByRole('menu', {name: 'File', hidden: true});+ await waitFor(() => expect(menu).toHaveFocus());+ act(() => row(/Export/).focus());+ await user.keyboard('{ArrowRight}');+ await waitFor(() => expect(row('PDF')).toHaveFocus());+ return {user, trigger, menu};+ }++ it('Tab on a flyout row closes every level and returns focus to the trigger, once', async () => {+ const onOpenChange = vi.fn();+ const {trigger, menu} = await openExport(onOpenChange);+ onOpenChange.mockClear();+ const tab = fireEvent.keyDown(row('PDF'), {key: 'Tab'});+ // Not prevented: the browser's Tab moves on from the trigger.+ expect(tab).toBe(true);+ expect(row(/Export/)).toHaveAttribute('aria-expanded', 'false');+ expect(menu.closest('[popover]')).not.toHaveAttribute('popover-open');+ expect(onOpenChange).toHaveBeenCalledTimes(1);+ expect(onOpenChange).toHaveBeenCalledWith(false);+ expect(trigger).toHaveFocus();+ });++ it('Shift+Tab on a flyout row closes every level too', async () => {+ const onOpenChange = vi.fn();+ const {menu} = await openExport(onOpenChange);+ onOpenChange.mockClear();+ fireEvent.keyDown(row('PDF'), {key: 'Tab', shiftKey: true});+ expect(menu.closest('[popover]')).not.toHaveAttribute('popover-open');+ expect(onOpenChange).toHaveBeenCalledTimes(1);+ expect(onOpenChange).toHaveBeenCalledWith(false);+ });++ it('Tab two levels down closes every level', async () => {+ const onOpenChange = vi.fn();+ const {user, trigger, menu} = await openExport(onOpenChange);+ act(() => row(/Image/).focus());+ await user.keyboard('{ArrowRight}');+ await waitFor(() => expect(row('PNG')).toHaveFocus());+ onOpenChange.mockClear();+ fireEvent.keyDown(row('PNG'), {key: 'Tab'});+ expect(row(/Image/)).toHaveAttribute('aria-expanded', 'false');+ expect(row(/Export/)).toHaveAttribute('aria-expanded', 'false');+ expect(menu.closest('[popover]')).not.toHaveAttribute('popover-open');+ expect(onOpenChange).toHaveBeenCalledTimes(1);+ expect(trigger).toHaveFocus();+ });+});diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsxindex 587058bff3..178a298733 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx@@ -63,7 +63,6 @@ import {createPortal} from 'react-dom';import * as stylex from '@stylexjs/stylex';import {Icon, renderIconSlot, type IconType} from '../Icon';import {Spinner} from '../Spinner';-import {MenuRegionsContext} from './menuRegionsContext';import {moveRegionsTab} from './menuRegionStops';import {Item} from '../Item';import {useLayer} from '../Layer/useLayer';@@ -518,7 +517,6 @@ export function DropdownMenuSubMenu(const t = useComponentTranslator();const menuCtx = useDropdownMenuContext();const rootSurface = use(DropdownMenuSurfaceContext);- const rootHasRegions = use(MenuRegionsContext);const menuSize = menuCtx?.menuSize ?? 'md';const canOpen = !isDisabled;// With a header or footer the sub-menu's surface holds controls that are not@@ -925,14 +923,13 @@ export function DropdownMenuSubMenu();return;}- // In a menu with a header or footer above this level, Tab leaves the- // flyout stack: every open level closes as the key bubbles past it,- // this one's own rows or a deeper level's, and the level with the- // regions moves focus on.- if (rootHasRegions) {- close({focusTrigger: false});- return;- }+ // Otherwise Tab leaves the flyout stack: every open level closes as+ // the key bubbles past it, this one's own rows or a deeper level's.+ // In a menu with a header or footer above this level, that level+ // moves focus on; in a plain menu the root closes the whole menu,+ // and focus moves on from its trigger (APG menu button).+ close({focusTrigger: false});+ return;}if (!ownsEvent(e)) {return;@@ -981,15 +978,7 @@ export function DropdownMenuSubMenu(}listNavKeyDown(e);},- [- ownsEvent,- close,- listNavKeyDown,- typeahead,- menuRef,- rootHasRegions,- hasRegions,- ],+ [ownsEvent, close, listNavKeyDown, typeahead, menuRef, hasRegions],);// A region keeps its own keys: arrows move a field's caret and letters type.@@ -1102,9 +1091,6 @@ export function DropdownMenuSubMenu(</DropdownMenuSurfaceContext></DropdownMenuContext>);- // A level with its own header or footer tells the levels below it, so Tab- // from a deeper flyout closes that flyout and this level walks on.- //// Nested rows live in this level's flyout, a layer of their own where the// layer-scoped signal resets; re-provide it, as whether every level above// them is open, so their pending hover intent dies with the root menu or@@ -1112,11 +1098,7 @@ export function DropdownMenuSubMenu(// leave a flyout with a header or footer shown beside the root's menu.const nestedContent = (<DropdownMenuRootOpenContext value={isRootMenuOpen && isOpen}>- {hasRegions ? (- <MenuRegionsContext value={true}>{nestedRows}</MenuRegionsContext>- ) : (- nestedRows- )}+ {nestedRows}</DropdownMenuRootOpenContext>);diff --git a/packages/core/src/DropdownMenu/menuRegionsContext.ts b/packages/core/src/DropdownMenu/menuRegionsContext.tsdeleted file mode 100644index f9159f7ec6..0000000000--- a/packages/core/src/DropdownMenu/menuRegionsContext.ts+++ /dev/null@@ -1,17 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.-'use client';-/**- * @file menuRegionsContext.ts- * @input DropdownMenu's `header` and `footer` props- * @output `MenuRegionsContext`: whether the root menu has a header or footer- * @position Internal; not exported from the package. A sub-menu flyout reads it- * to close itself on Tab, so the root menu can move focus to a region.- *- * A plain context rather than a layer-scoped one on purpose: each sub-menu- * flyout is its own layer, and it must still see the root's value. A nested- * DropdownMenu provides its own value, so it never inherits an outer one.- */-import {createContext} from 'react';--export const MenuRegionsContext = createContext(false);-MenuRegionsContext.displayName = 'MenuRegionsContext';