An open source design system that's fully customizable and agent ready
TypeScript
fix(menus): the keys and type-ahead reach a disabled row, which stays inert (#10160)
Cindy Zhangdd09d678d6ae
diff --git a/.changeset/menu-disabled-rows-reachable.md b/.changeset/menu-disabled-rows-reachable.mdnew file mode 100644index 0000000000..90f06dd418--- /dev/null+++ b/.changeset/menu-disabled-rows-reachable.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Menus: the arrow keys, Home, End and type-ahead now reach a disabled row in `DropdownMenu`, its sub-menus, `MoreMenu`, `ContextMenu` and `NavHeadingMenu`, so a keyboard or screen-reader user finds the row and its description. The row takes focus, is announced as disabled, and Enter, Space or a click on it still does nothing and leaves the menu open. Opening a menu from the keyboard still lands on an enabled row.++@cixzhangdiff --git a/docs/specs/components/ContextMenu/ContextMenu.spec.md b/docs/specs/components/ContextMenu/ContextMenu.spec.mdindex 9fa7503274..8eb98c0f25 100644--- a/docs/specs/components/ContextMenu/ContextMenu.spec.md+++ b/docs/specs/components/ContextMenu/ContextMenu.spec.md@@ -109,7 +109,7 @@ Consumer props, content modes, and presentation policy remain documented in| FR5 | The Pointer menu surface carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR7: the row under the release acts, the highlight follows a held pointer, a mouse released outside closes and a finger leaves the menu open, the stray click never acts, and `touch-action` follows overflow. The long press that opened the menu does not close it as it lifts; a tap outside closes it, and a mouse press outside closes it at the press. Under a finger the menu MUST close as a pan that starts outside it begins (`spec:AST-094` FR32), MUST hand the held finger that opened it to the menu as the opening press, and MUST treat a pen's press outside as FR32 does (FR33). The lift and the grow apply only to a menu opened by touch (a touch-initiated open on a coarse pointer); a menu opened by mouse or keyboard keeps its released appearance and motion, with no lift, no tint and no grow. A touch-opened menu MUST grow out of the finger's point and shrink back into it (`spec:AST-094` FR31) as its own surface, by transform and opacity only (`spec:AST-094` FR5), with no second element such as a glass surface growing behind it, and on a block trigger MUST lift the trigger above the page with the menu beside it (FR33; DD1, DEC-2). The long-press presentation is a gesture component, so the trigger's lift plays `springs.contextMenuLift`, the menu's grow `springs.contextMenuMorph`, and the trigger's return, part of the menu's exit, `springs.contextMenuDismiss` (`spec:AST-094` FR4, FR7, FR45). Implementation gap: it keeps the layer's own entrance and exit, a scroll that starts outside leaves it open, the opening finger is not handed to the menu so it cannot slide to a row, no trigger lift or page tint exists, and a pen press outside closes it at the press. Right-click, Shift+F10, long-press invocation, and keyboard navigation are as FR1 and FR8 state. | `module:DropdownMenu/useMenuPress`; `spec:AST-094` FR26–FR33 || FR6 | With `triggerAs="span"` the Trigger area is an inline element that owns a box, so the cursor anchor measures from the trigger's own rect on every invocation path. Right-click, Shift+F10, long-press, and `context-menu` target placement all use that box. | DEC-1 || FR7 | Sub-menu rows follow `component:DropdownMenu` FR11 inside the pointer menu: ContextMenu mounts the same drill-in view stack, named after its `label`, so a sub-menu drills in on a phone here too. A sub-menu with a header or footer shows its rows alone here (`component:DropdownMenu` FR20). | `component:DropdownMenu/DEC-4` |-| 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 |+| 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. | 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 |@@ -265,9 +265,6 @@ anchor is positioning infrastructure rather than consumer anatomy.## Current-state impact-- **Disabled rows skipped (FR8).** The arrow keys and typeahead skip disabled- rows instead of reaching them as `component:DropdownMenu` FR17 and DEC-11- state.- **No headless factory (FR10).** No headless context menu ships, so ContextMenuowns its invocation, open state, and outside-press listener itself, against`spec:AST-107` FR8.diff --git a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenu.spec.mdindex 40994a222a..d76ed47a82 100644--- a/docs/specs/components/DropdownMenu/DropdownMenu.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenu.spec.md@@ -39,15 +39,15 @@ system_specs: [spec:AST-020/FR15, spec:AST-094, spec:AST-102]## Contract at a glance-| Area | Contract |-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | None changes. DropdownMenu takes a `button` (Button props) or `renderTrigger`, data-driven `items` or compound children, `presentation`, `isMenuOpen` and `onOpenChange`, placement and alignment, `menuMaxHeight`, `header`, and `footer`. |-| Behavior | A Menu Button trigger opens an anchored pointer menu or a bottom-sheet action list. Rows act on the release under the shared press model; sub-menus fly out beside their row or drill in on a compact touch display; a header or footer makes the pointer popover a modal dialog around the menu. |-| End-user impact | People pick actions by mouse, finger, or keyboard; keyboard users get a focus return with a ring and pointer users without one; on a phone sub-menus replace the rows instead of flying off-screen. Under a finger the menu opens after a 500 ms hold or at a tap's click, does not grow from its trigger, and a pan outside does not close it. |-| Builder impact | Builders choose the trigger, the rows, and the regions; rows stay menu items and every non-item control goes in `header` or `footer`. |-| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains `tabindex="-1"`; the released behavior under a finger moves as `spec:AST-094` FR25 lists, with `presentation="popover"` keeping it. Finger press-open (FR8), touch grow and pan dismissal (FR21), the still mouse (FR22), disabled-row keyboard reach (FR12, FR17), and Trigger Button gaps are in Current-state impact. |-| Review checks | Reject a control placed among the rows, a lost trigger ARIA wiring, a drilled-in view that leaves the menu box, a header or footer without the dialog, a lost focus-return modality, or a target moved off its painted element. |-| Governing rules | `spec:AST-020` FR15; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `architecture:interaction-modality` INV1; `architecture:component-theming-surface`; `architecture:layer-runtime`; `family:overlay-dismissal`; `family:navigation-destinations`. |+| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | None changes. DropdownMenu takes a `button` (Button props) or `renderTrigger`, data-driven `items` or compound children, `presentation`, `isMenuOpen` and `onOpenChange`, placement and alignment, `menuMaxHeight`, `header`, and `footer`. |+| Behavior | A Menu Button trigger opens an anchored pointer menu or a bottom-sheet action list. Rows act on the release under the shared press model; sub-menus fly out beside their row or drill in on a compact touch display; a header or footer makes the pointer popover a modal dialog around the menu. |+| End-user impact | People pick actions by mouse, finger, or keyboard; keyboard users get a focus return with a ring and pointer users without one; on a phone sub-menus replace the rows instead of flying off-screen. Under a finger the menu opens after a 500 ms hold or at a tap's click, does not grow from its trigger, and a pan outside does not close it. |+| Builder impact | Builders choose the trigger, the rows, and the regions; rows stay menu items and every non-item control goes in `header` or `footer`. |+| Compatibility/readiness | Records shipped behavior; no API change; a disabled row gains `tabindex="-1"`; the released behavior under a finger moves as `spec:AST-094` FR25 lists, with `presentation="popover"` keeping it. Finger press-open (FR8), touch grow and pan dismissal (FR21), the still mouse (FR22), and Trigger Button gaps are in Current-state impact. |+| Review checks | Reject a control placed among the rows, a lost trigger ARIA wiring, a drilled-in view that leaves the menu box, a header or footer without the dialog, a lost focus-return modality, or a target moved off its painted element. |+| Governing rules | `spec:AST-020` FR15; `spec:AST-094` FR26–FR35; `module:DropdownMenu/useMenuPress`; `architecture:interaction-modality` INV1; `architecture:component-theming-surface`; `architecture:layer-runtime`; `family:overlay-dismissal`; `family:navigation-destinations`. |This table is a review projection; the body below is authoritative.@@ -140,7 +140,7 @@ component-local concepts; each keeps its released default.| FR14 | Compound groups follow `component:DropdownMenuGroup`; a data-mode `{type: 'section'}` entry is a `role="group"` named by its title, and an untitled section renders its rows without a heading. | DEC-6; current tests || FR15 | With `header` or `footer`, the pointer popover is a `role="dialog"` with `aria-modal="true"`, named like the menu, holding the header, then the `role="menu"` element, then the footer; the menu element holds only its rows. The trigger says `aria-haspopup="dialog"` and its `aria-controls` names the popover that holds the dialog. A region keeps its own keys and presses: neither the menu's key handling nor its press model claims an event that begins there. The menu is one Tab stop between the regions. Tab and Shift+Tab move through the header's controls, the menu, then the footer's controls, and wrap at either end; a control that is hidden, or under a hidden ancestor within its region, is not a stop. From a row, or a row of an open sub-menu, Tab and Shift+Tab close every open flyout and continue from the menu's stop. With no other stop, focus stays in the menu. Escape closes from anywhere in the popover, and focus returns to the trigger. The bottom sheet, already a dialog, shows the header above the actions and the footer below them. Without either prop, the menu renders and behaves exactly as it does without them: no dialog, `aria-haspopup="menu"`, and Tab closes the menu. | DEC-8, DEC-10 || FR16 | Checkbox rows follow `component:DropdownMenuCheckboxItem`. | Current source |-| FR17 | A disabled menu row MUST be reached by the keyboard and stay inert (DEC-11): in DropdownMenu, its sub-menus, MoreMenu, ContextMenu and NavHeadingMenu, ArrowDown, ArrowUp, Home, End and type-ahead visit a disabled row as they visit any other row, the row takes focus and exposes `aria-disabled="true"`, and Enter, Space or a click on it does nothing and leaves the menu open. Opening a menu from the keyboard still lands on an enabled row: the first, or the last after ArrowUp on the trigger (FR12, AR4). Implementation gap: the arrow keys and type-ahead skip disabled rows today. | DEC-11; WAI-ARIA Menu pattern |+| FR17 | A disabled menu row MUST be reached by the keyboard and stay inert (DEC-11): in DropdownMenu, its sub-menus, MoreMenu, ContextMenu and NavHeadingMenu, ArrowDown, ArrowUp, Home, End and type-ahead visit a disabled row as they visit any other row, the row takes focus and exposes `aria-disabled="true"`, and Enter, Space or a click on it does nothing and leaves the menu open. Opening a menu from the keyboard still lands on an enabled row: the first, or the last after ArrowUp on the trigger (FR12, AR4). | DEC-11; WAI-ARIA Menu pattern || 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 unless the mouse rests where the page last heard it when the shield came up (`spec:AST-094` FR35). | `spec:AST-094` FR35; `architecture:layer-runtime` |@@ -385,9 +385,6 @@ than adding a DropdownMenu-owned heading target.- **Rich sheet heading for caller-rendered triggers (OQ2).** With`renderTrigger`, the bottom-sheet heading shows only the flattened text ofthe trigger's accessible name, and a trigger with no name gets no heading.-- **Disabled rows skipped (FR12, FR17).** The arrow keys and type-ahead skip- disabled rows, including checkbox and radio rows, instead of reaching them- as DEC-11 states.## Decision logdiff --git a/docs/specs/components/DropdownMenu/DropdownMenuCheckboxItem.spec.md b/docs/specs/components/DropdownMenu/DropdownMenuCheckboxItem.spec.mdindex 3d6feebb62..6c8c13f2ca 100644--- a/docs/specs/components/DropdownMenu/DropdownMenuCheckboxItem.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenuCheckboxItem.spec.md@@ -93,7 +93,7 @@ Consumer migration instructions belong in consumer docs and release notes.| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- || FR1 | The row renders one element with `role="menuitemcheckbox"` whose `aria-checked` equals `value`; the checkbox marker is decorative (`aria-hidden`), so the row is the only announced control. | `spec:AST-020` FR15; current source and tests || FR2 | An enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls `onChange(!value)`, then closes the menu when `hasCloseOnSelect` is set, then calls the caller's `onClick`; without `hasCloseOnSelect` the menu stays open. The APG Menu pattern's Enter closes the menu, and `spec:AST-020` FR15 requires this record to name any required part it does not adopt. Implementation gap: Enter keeps the menu open by default, and no exception is named (OQ1). | `spec:AST-020` FR15; `architecture:public-component-api` INV7; current tests |-| FR3 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` like an enabled row so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), and on any activation calls neither `onChange` nor the caller's activation handlers and does not close the menu. Implementation gap: a disabled row renders no `tabindex` today. | Current source and tests |+| FR3 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` like an enabled row so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), and on any activation calls neither `onChange` nor the caller's activation handlers and does not close the menu. | Current source and tests || FR4 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root; caller `onPointerMove` composes with the row's hover focus. | `architecture:public-component-api` INV5–INV8; current tests || FR5 | The marker is the shared checkbox Indicator, `sm` in a small menu; the row carries the `dropdown-menu-item` target with the menu size. | `architecture:component-theming-surface`; current source and tests || FR6 | The row adds no key handler or tab stop of its own: every row, disabled included, is `tabindex="-1"` for the parent's roving focus, and the parent's keyboard reaches a disabled row (`component:DropdownMenu` FR17). | `architecture:interaction-modality`; parent tests |@@ -167,9 +167,6 @@ anatomy-theming map.## Current-state impact-- **Disabled rows skipped (FR3, FR6).** A disabled row renders no `tabindex`, so- the parent's arrow keys and type-ahead skip it instead of reaching it as- `component:DropdownMenu` FR17 and DEC-11 state.- **Enter keeps the menu open (FR2).** Enter on a checkbox row toggles it andleaves the menu open by default, against the Menu pattern's Enter that`spec:AST-020` FR15 adopts, with no named exception (OQ1).diff --git a/docs/specs/components/DropdownMenu/DropdownMenuItem.spec.md b/docs/specs/components/DropdownMenu/DropdownMenuItem.spec.mdindex 4ca2dfe852..87db28318f 100644--- a/docs/specs/components/DropdownMenu/DropdownMenuItem.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenuItem.spec.md@@ -194,9 +194,7 @@ No component-local visual decision is recorded.## Current-state impact-- **Disabled rows skipped (FR7).** A disabled row renders no `tabIndex`, so the- parent's arrow keys and type-ahead skip it instead of reaching it as- `component:DropdownMenu` FR17 and DEC-11 state.+None.## Decision logdiff --git a/docs/specs/components/DropdownMenu/DropdownMenuRadioItem.spec.md b/docs/specs/components/DropdownMenu/DropdownMenuRadioItem.spec.mdindex 7f8ef220e2..52855bad93 100644--- a/docs/specs/components/DropdownMenu/DropdownMenuRadioItem.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenuRadioItem.spec.md@@ -105,16 +105,16 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |-| FR1 | The row renders one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It nests no native or ARIA radio. | `spec:AST-020`; current source and tests |-| FR2 | Rendering the row outside a DropdownMenuRadioGroup throws. | Current source and focused tests |-| FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls the group `onChange` with the row value, then asks DropdownMenu to close when the group's close policy is on, then calls the caller `onClick`. | `architecture:public-component-api` INV7; current behavior and tests |-| FR4 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` like an enabled row so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), takes no hover focus, and on any activation, including an assistive-technology click, calls neither `onChange` nor the caller `onClick` and does not close the menu. It paints at half opacity with a default cursor. Implementation gap: a disabled row renders no `tabindex` today. | Current source and tests |-| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root. Caller `onPointerMove` runs after the row's hover focus, and caller handlers do not replace the row's own behavior. | `architecture:public-component-api` INV5–INV8; current tests |-| FR6 | The marker is the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer. | Current source and tests |-| FR7 | The row carries the `dropdown-menu-item` target with the menu size and the marker carries the `dropdown-menu-radio` target with size, checked, and disabled reflections. | `architecture:component-theming-surface`; current source and docs |-| FR8 | The row adds no key handler or tab stop of its own: every row, disabled included, is `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click. | `architecture:interaction-modality`; parent keyboard tests |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |+| FR1 | The row renders one element with `role="menuitemradio"` whose `aria-checked` is true exactly when the group value equals the row value. It nests no native or ARIA radio. | `spec:AST-020`; current source and tests |+| FR2 | Rendering the row outside a DropdownMenuRadioGroup throws. | Current source and focused tests |+| FR3 | Enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls the group `onChange` with the row value, then asks DropdownMenu to close when the group's close policy is on, then calls the caller `onClick`. | `architecture:public-component-api` INV7; current behavior and tests |+| FR4 | A disabled row exposes `aria-disabled="true"`, carries `tabindex="-1"` like an enabled row so the parent's keyboard model reaches it (`component:DropdownMenu` FR17), takes no hover focus, and on any activation, including an assistive-technology click, calls neither `onChange` nor the caller `onClick` and does not close the menu. It paints at half opacity with a default cursor. | Current source and tests |+| FR5 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root. Caller `onPointerMove` runs after the row's hover focus, and caller handlers do not replace the row's own behavior. | `architecture:public-component-api` INV5–INV8; current tests |+| FR6 | The marker is the shared radio Indicator, hidden from assistive technology, never the pointer target, sized `sm` in a small menu and `md` otherwise, at the row's inline start on a fine pointer and its inline end on a coarse pointer. | Current source and tests |+| FR7 | The row carries the `dropdown-menu-item` target with the menu size and the marker carries the `dropdown-menu-radio` target with size, checked, and disabled reflections. | `architecture:component-theming-surface`; current source and docs |+| FR8 | The row adds no key handler or tab stop of its own: every row, disabled included, is `tabindex="-1"` for the parent's roving focus, and keyboard selection arrives as the parent's synthesized click. | `architecture:interaction-modality`; parent keyboard tests |### Allowed variation@@ -205,9 +205,7 @@ No component-local visual decision is recorded.## Current-state impact-- **Disabled rows skipped (FR4, FR8).** A disabled row renders no `tabindex`, so- the parent's arrow keys and type-ahead skip it instead of reaching it as- `component:DropdownMenu` FR17 and DEC-11 state.+None.## Decision logdiff --git a/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md b/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.mdindex 2b7ddfb36c..70d76c0c03 100644--- a/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md+++ b/docs/specs/components/DropdownMenu/DropdownMenuSubMenu.spec.md@@ -109,19 +109,19 @@ 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 |-| 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 |-| FR11 | On a hover-capable pointer, the flyout opens after `delay` and closes `hideDelay` after the pointer has left the row, the flyout and the path toward it (`component:DropdownMenu` FR13), in milliseconds (defaults 150 and 200). Keyboard focus and touch never wait. | Owner decision, 2026-11-06 |+| 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`. | 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 |+| FR11 | On a hover-capable pointer, the flyout opens after `delay` and closes `hideDelay` after the pointer has left the row, the flyout and the path toward it (`component:DropdownMenu` FR13), in milliseconds (defaults 150 and 200). Keyboard focus and touch never wait. | Owner decision, 2026-11-06 |### Allowed variation@@ -212,9 +212,6 @@ No component-local visual decision is recorded.## Current-state impact-- **Disabled rows skipped (FR7).** A disabled row renders no `tabindex`, so the- parent's arrow keys and type-ahead skip it instead of reaching it as- `component:DropdownMenu` FR17 and DEC-11 state.- **Drill-in close report (FR6).** When the root menu closes a drilled-in view,`onOpenChange(false)` does not run (OQ1).diff --git a/docs/specs/components/NavMenu/NavHeadingMenu.spec.md b/docs/specs/components/NavMenu/NavHeadingMenu.spec.mdindex 241416a156..9af61fbe53 100644--- a/docs/specs/components/NavMenu/NavHeadingMenu.spec.md+++ b/docs/specs/components/NavMenu/NavHeadingMenu.spec.md@@ -45,7 +45,7 @@ system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]| Behavior | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu. || End-user impact | Users switch products or accounts from the heading menu by pointer or keyboard; keyboard and typeahead reach disabled rows, which are announced as disabled and do nothing (FR6). || Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no API change; a disabled item gains `tabindex="-1"` (FR6). Six implementation gaps (see Current-state impact). |+| Compatibility/readiness | Records shipped behavior; no API change; a disabled item gains `tabindex="-1"` (FR6). Four implementation gaps (see Current-state impact). || Review checks | Reject losing `menu`/`menuitem` roles to caller props, keyboard movement or typeahead that skips a disabled item, a disabled item that acts or closes the menu, or a caller `onKeyDown` that silently disables the keyboard model. || Governing rules | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`. |@@ -88,13 +88,6 @@ Consumer migration instructions belong in consumer docs and release notes.accessible name unless the caller passes `aria-label`; inside a heading onlythe heading's wrapper `menu` is named. The APG menu pattern, which`spec:AST-020` FR15 adopts, names each menu.-- **A disabled item changes focusability.** A disabled item drops the- `tabIndex=-1` enabled items carry: a disabled link item becomes a page tab- stop, and a disabled action item cannot take focus at all. `spec:AST-085` FR1- keeps a disabled control's focus order as it is when enabled.-- **Disabled items skipped (FR5, FR6).** Keyboard movement and typeahead skip- disabled items instead of reaching them as `component:DropdownMenu` FR17 and- DEC-11 state.- **Focus is shown only by fill.** An item removes the outline and marks focuswith the hover fill; it does not use the shared focus outline that`architecture:interaction-modality` provides.@@ -137,8 +130,8 @@ Consumer migration instructions belong in consumer docs and release notes.| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target with the menu's size, as the `LinkProvider` link (else `<a>`) when `href` is supplied and a `div` otherwise. Caller props cannot replace its role, tab index, or disabled state. | Current source, docs, and tests || FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target on one line; non-string labels render directly as caller-owned content. | Current source and target docs || FR4 | The host heading owns the popup runtime. Where it supplies a close callback (TopNavHeading and the collapsed SideNavHeading), NavHeadingMenu calls it on Escape and on successful Item selection; an expanded SideNavHeading supplies none, so the menu stays open after a choice (`component:SideNavHeading` FR7). | Current source and tests |-| FR5 | Items, disabled ones included, are focusable but not tab stops. In a standalone menu, ArrowDown and ArrowUp move one item, disabled included, and wrap; Home and End go to the first and last item; typing a character moves to the matching item, disabled included (FR6, `component:DropdownMenu` FR17); Enter or Space activates the focused item. Implementation gap: movement and typeahead skip disabled items (Current-state impact). | Current source and tests |-| FR6 | Activating an enabled item runs its `onClick` and then the close callback; a disabled item carries `aria-disabled="true"`, MUST stay focusable outside the tab order as an enabled item is (`spec:AST-085` FR1), is reached by keyboard movement and typeahead as `component:DropdownMenu` FR17 states (owner decision, 2026-11-04, `component:DropdownMenu` DEC-11), and does not run `onClick` or close the menu. Implementation gap: a disabled item drops `tabIndex=-1`, and keyboard movement and typeahead skip it (Current-state impact). | Current source and tests |+| FR5 | Items, disabled ones included, are focusable but not tab stops. In a standalone menu, ArrowDown and ArrowUp move one item, disabled included, and wrap; Home and End go to the first and last item; typing a character moves to the matching item, disabled included (FR6, `component:DropdownMenu` FR17); Enter or Space activates the focused item. | Current source and tests |+| FR6 | Activating an enabled item runs its `onClick` and then the close callback; a disabled item carries `aria-disabled="true"`, MUST stay focusable outside the tab order as an enabled item is (`spec:AST-085` FR1), is reached by keyboard movement and typeahead as `component:DropdownMenu` FR17 states (owner decision, 2026-11-04, `component:DropdownMenu` DEC-11), and does not run `onClick` or close the menu. | Current source and tests || FR7 | A caller `onKeyDown` on the menu runs first; the keyboard model still runs unless that caller calls `preventDefault()` on an event no item handler has already cancelled; an item handler that cancels does not stop arrow navigation. | Current source and tests || FR8 | In the open menu, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests |diff --git a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.jsonindex 1d1ecd3e7b..b67aa2e22f 100644--- a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json+++ b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json@@ -730,11 +730,9 @@"family:action-groups"],"packages/core/src/NavMenu/NavHeadingMenuItem.tsx": [- "FR1","FR2","FR4","spec:AST-085",- "spec:AST-085","spec:AST-085"],"packages/core/src/NavMenu/NavMenuContext.tsx": ["FR7"],diff --git a/packages/core/src/ContextMenu/ContextMenu.test.tsx b/packages/core/src/ContextMenu/ContextMenu.test.tsxindex d68f7a78dc..0c57e98688 100644--- a/packages/core/src/ContextMenu/ContextMenu.test.tsx+++ b/packages/core/src/ContextMenu/ContextMenu.test.tsx@@ -1366,7 +1366,7 @@ describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)).toHaveFocus();});- it('typeahead skips an aria-disabled item and matches the next enabled label', () => {+ it('typeahead reaches an aria-disabled item, which stays discoverable', () => {render(<ContextMenumenuContent={@@ -1387,21 +1387,14 @@ describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)fireEvent.contextMenu(screen.getByText('Right-click me'));// Anchor the search on 'Cut' so typeahead scans forward and meets the// disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.- // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the- // menus never pass useTypeahead's `isDisabled` option, so that clause is- // the only thing keeping disabled rows out of the typeahead list. An- // arrow-key test cannot cover it — useListFocus re-filters disabled items- // independently, so arrow navigation is guarded twice over.- // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so- // the selector clause is the sole reason focus skips it.screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});expect(- screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),+ screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),).toHaveFocus();});- it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', () => {+ it('reaches aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', () => {render(<ContextMenumenuContent={@@ -1428,7 +1421,11 @@ describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)fireEvent.keyDown(menu, {key: 'ArrowDown'});expect(- screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),+ screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),+ ).toHaveFocus();+ fireEvent.keyDown(menu, {key: 'ArrowDown'});+ expect(+ screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),).toHaveFocus();});diff --git a/packages/core/src/ContextMenu/ContextMenu.tsx b/packages/core/src/ContextMenu/ContextMenu.tsxindex b3b1536ec9..66ba1dfda6 100644--- a/packages/core/src/ContextMenu/ContextMenu.tsx+++ b/packages/core/src/ContextMenu/ContextMenu.tsx@@ -71,6 +71,7 @@ import {import {MENU_ITEM_ROLES,MENU_ITEM_SELECTOR,+ MENU_ROW_SELECTOR,MENU_BOUNDARY_SELECTOR,activateMenuItem,} from '../DropdownMenu/menuItemRoles';@@ -479,7 +480,8 @@ export function ContextMenu({ownsEvent,getItems: getMenuItems,} = useInternalListFocus<HTMLDivElement>({- itemSelector: MENU_ITEM_SELECTOR,+ itemSelector: MENU_ROW_SELECTOR,+ reachesDisabledItems: true,boundarySelector: MENU_BOUNDARY_SELECTOR,// Menus wrap from the last row to the first and back.wrap: true,@@ -498,7 +500,8 @@ export function ContextMenu({getContainer: () => listRef.current,});- // Typeahead over the enabled menu items, matched on each row's LABEL alone.+ // Typeahead over the menu items, disabled ones included, matched on each+ // row's LABEL alone.// Reuses the hook's scoped item collection so an inline submenu flyout's// items aren't swept in.const typeahead = useTypeahead({diff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsxindex f6143dedef..14d7c67763 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx@@ -2449,7 +2449,7 @@ describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829).toHaveFocus();});- it('typeahead skips an aria-disabled item and matches the next enabled label', async () => {+ it('typeahead reaches an aria-disabled item, which stays discoverable', async () => {const user = userEvent.setup();render(<DropdownMenu button={{label: 'Sort'}}>@@ -2466,21 +2466,14 @@ describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829await user.click(screen.getByRole('button', {name: /Sort/}));// Anchor the search on 'Edit' so typeahead scans forward and meets the// disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.- // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the- // menus never pass useTypeahead's `isDisabled` option, so that clause is- // the only thing keeping disabled rows out of the typeahead list. An- // arrow-key test cannot cover it — useListFocus re-filters disabled items- // independently, so arrow navigation is guarded twice over.- // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so- // the selector clause is the sole reason focus skips it.screen.getByRole('menuitem', {name: 'Edit', hidden: true}).focus();fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});expect(- screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),+ screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),).toHaveFocus();});- it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', async () => {+ it('reaches aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', async () => {const user = userEvent.setup();render(<DropdownMenu button={{label: 'Sort'}}>@@ -2503,7 +2496,86 @@ describe('DropdownMenu keyboard access for menuitemradio/menuitemcheckbox (#3829fireEvent.keyDown(menu, {key: 'ArrowDown'});expect(- screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),+ screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),+ ).toHaveFocus();+ fireEvent.keyDown(menu, {key: 'ArrowDown'});+ expect(+ screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),+ ).toHaveFocus();+ });++ it("a disabled row keeps a mouse press's focus off and still runs the caller's onMouseDown", async () => {+ const user = userEvent.setup();+ const onMouseDown = vi.fn();+ render(+ <DropdownMenu button={{label: 'Actions'}}>+ <DropdownMenuItem label="Edit" onClick={() => {}} />+ <DropdownMenuItem+ label="Delete"+ isDisabled+ onClick={() => {}}+ onMouseDown={onMouseDown}+ />+ </DropdownMenu>,+ );+ await user.click(screen.getByRole('button', {name: /Actions/}));+ const del = screen.getByRole('menuitem', {name: 'Delete', hidden: true});+ expect(fireEvent.mouseDown(del)).toBe(false);+ expect(onMouseDown).toHaveBeenCalledOnce();+ });++ it('a disabled row takes focus from the keys, stays inert, and leaves the menu open', async () => {+ const user = userEvent.setup();+ const onDelete = vi.fn();+ render(+ <DropdownMenu+ button={{label: 'Actions'}}+ items={[+ {label: 'Edit'},+ {+ label: 'Delete',+ isDisabled: true,+ description: 'Only the owner can delete',+ onClick: onDelete,+ },+ {label: 'Print'},+ ]}+ />,+ );++ screen.getByRole('button', {name: /Actions/}).focus();+ await user.keyboard('{Enter}');+ const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});+ await waitFor(() => expect(edit).toHaveFocus());++ const del = screen.getByRole('menuitem', {name: /Delete/, hidden: true});+ expect(del).toHaveAttribute('aria-disabled', 'true');+ expect(del).toHaveAttribute('tabindex', '-1');+ await user.keyboard('{ArrowDown}');+ expect(del).toHaveFocus();+ await user.keyboard('{Enter}');+ await user.keyboard(' ');+ expect(onDelete).not.toHaveBeenCalled();+ expect(screen.getByRole('button', {name: /Actions/})).toHaveAttribute(+ 'aria-expanded',+ 'true',+ );+ expect(del).toHaveFocus();++ // A mouse press on the disabled row does not focus or light it.+ fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {+ key: 'Home',+ });+ expect(fireEvent.mouseDown(del)).toBe(false);+ expect(fireEvent.mouseDown(edit)).toBe(true);++ // End and Home move to the first and last rows, as from any row.+ const menu = screen.getByRole('menu', {hidden: true});+ fireEvent.keyDown(menu, {key: 'Home'});+ expect(edit).toHaveFocus();+ fireEvent.keyDown(menu, {key: 'End'});+ expect(+ screen.getByRole('menuitem', {name: 'Print', hidden: true}),).toHaveFocus();});@@ -2648,7 +2720,7 @@ describe('DropdownMenu open focus follows input modality (#4477)', () => {).toHaveFocus();});- it('ArrowDown after a pointer open skips a disabled leading item', async () => {+ it('ArrowDown after a pointer open reaches a disabled leading item', async () => {const user = userEvent.setup();render(<DropdownMenu@@ -2663,7 +2735,7 @@ describe('DropdownMenu open focus follows input modality (#4477)', () => {fireEvent.keyDown(menu, {key: 'ArrowDown'});expect(- screen.getByRole('menuitem', {name: 'Delete', hidden: true}),+ screen.getByRole('menuitem', {name: 'Edit', hidden: true}),).toHaveFocus();});diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsxindex 3eab074bf5..a0c1b8e460 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx@@ -58,6 +58,7 @@ import type {DropdownMenuItemProps} from './DropdownMenuItem';import {MENU_ITEM_ROLES,MENU_ITEM_SELECTOR,+ MENU_ROW_SELECTOR,MENU_BOUNDARY_SELECTOR,activateMenuItem,} from './menuItemRoles';@@ -71,7 +72,7 @@ import {} from './DropdownMenuContext';import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';import {useMergedRefs} from '../hooks/useMergedRefs';-import {useListFocus} from '../hooks/useListFocus';+import {useInternalListFocus} from '../hooks/useListFocus';import {useDropdownMenuPress} from '../hooks/useMenuPress';import type {MenuPressPointerType} from '../hooks/menuPressGesture';import {useTypeahead} from '../hooks/useTypeahead';@@ -1134,8 +1135,9 @@ function DropdownMenuPopover({focusItem,ownsEvent,getItems: getMenuItems,- } = useListFocus<HTMLDivElement>({- itemSelector: MENU_ITEM_SELECTOR,+ } = useInternalListFocus<HTMLDivElement>({+ itemSelector: MENU_ROW_SELECTOR,+ reachesDisabledItems: true,boundarySelector: MENU_BOUNDARY_SELECTOR,// Menus wrap from the last row to the first and back, as macOS menus do;// a picker's list clamps instead.@@ -1144,7 +1146,7 @@ function DropdownMenuPopover({onEscape: closeMenu,});- // Typeahead over the (enabled) menu items — jump to the next item whose+ // Typeahead over the menu items, disabled ones included — jump to the next item whose// LABEL starts with the typed text, never its description, shortcut or// badge. Reuses the hook's scoped item collection so an inline submenu// flyout's items aren't swept in.diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjsindex 2cd1169b7f..fb102d0186 100644--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs@@ -70,7 +70,7 @@ export const docs = {type: 'boolean',default: 'false',description:- 'Whether the item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled) but takes no focus: the arrow keys, typeahead, and the pointer highlight skip it, and activation is blocked.',+ 'Whether the item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled), and the arrow keys and typeahead reach it so keyboard users find it. The pointer highlight skips it, and activation is blocked.',},{name: 'hasCloseOnSelect',@@ -134,7 +134,7 @@ export const docsDense = {value: 'checked state (controlled, w/ onChange)',onChange: 'fired w/ next checked state on toggle',isDisabled:- 'disabled (aria-disabled); skipped by arrows/typeahead, not focusable',+ 'disabled (aria-disabled); reached by arrows/typeahead, focusable, inert',hasCloseOnSelect: 'close menu on toggle (default false, stays open)',ref: 'forwarded to the row root (the role="menuitemcheckbox" element)',endContent: 'content after label+description',diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsxindex 08802d9c0b..74832db7bf 100644--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx@@ -43,6 +43,7 @@ import {focusMenuItemOnHover} from './menuItemHover';import {colorVars, focusVars, spacingVars} from '../theme/tokens.stylex';import {composeEventHandlers, mergeProps, themeProps} from '../utils';import type {BaseProps} from '../BaseProps';+import {keepDisabledRowUnfocused} from './menuItemRoles';const styles = stylex.create({root: {@@ -118,8 +119,9 @@ export interface DropdownMenuCheckboxItemProps extends Omit<onChange?: (checked: boolean) => void;/*** Whether the item is disabled. A disabled item stays in the accessibility- * tree as disabled (`aria-disabled`) but takes no focus: the arrow keys,- * typeahead, and the pointer highlight skip it, and activation is blocked.+ * tree as disabled (`aria-disabled`), and the arrow keys and typeahead reach+ * it so keyboard users find it. The pointer highlight skips it, and+ * activation is blocked.* @default false*/isDisabled?: boolean;@@ -204,9 +206,13 @@ export function DropdownMenuCheckboxItem({return (<Item{...rest}+ onMouseDown={composeEventHandlers(+ rest.onMouseDown,+ isDisabled ? keepDisabledRowUnfocused : undefined,+ )}role="menuitemcheckbox"aria-checked={value}- tabIndex={isDisabled ? undefined : -1}+ tabIndex={-1}onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}marker={// No wrapper, and no menu-specific theme target: the shareddiff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuItem.tsxindex ee009a52de..b071ec0715 100644--- a/packages/core/src/DropdownMenu/DropdownMenuItem.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.tsx@@ -51,7 +51,7 @@ import {useDropdownMenuContext} from './DropdownMenuContext';import {focusOutlineStyles} from '../utils/focusOutline.stylex';import {menuPressLitRowStyle} from '../privateAttributes/menuPressLit.stylex';import {focusMenuItemOnHover} from './menuItemHover';-import {isModifiedClick} from './menuItemRoles';+import {isModifiedClick, keepDisabledRowUnfocused} from './menuItemRoles';import {themeProps} from '../utils/themeProps';import {usePressFeedback} from '../hooks/usePressFeedback';@@ -270,6 +270,10 @@ export function DropdownMenuItem({return (<Item{...rest}+ onMouseDown={composeEventHandlers(+ rest.onMouseDown,+ isDisabled ? keepDisabledRowUnfocused : undefined,+ )}ref={ref}// A row that navigates IS the link: its root is the application's// anchor, so a modified click, a middle click, copying the address and@@ -277,7 +281,7 @@ export function DropdownMenuItem({// address keeps the default root.as={href != null ? LinkComponent : undefined}role="menuitem"- tabIndex={isDisabled ? undefined : -1}+ tabIndex={-1}// The row's own handling runs first, then the caller's.onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}{...pressable}diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjsindex 483a522f7f..067c94d706 100644--- a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs@@ -52,7 +52,7 @@ export const docs = {type: 'boolean',default: 'false',description:- 'Whether this individual radio item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled) but takes no focus: the arrow keys, typeahead, and the pointer highlight skip it, and selection is blocked.',+ 'Whether this individual radio item is disabled. A disabled item stays in the accessibility tree as disabled (aria-disabled), and the arrow keys and typeahead reach it so keyboard users find it. The pointer highlight skips it, and selection is blocked.',},{name: 'endContent',@@ -97,7 +97,7 @@ export const docsDense = {description: 'secondary text below label',icon: 'icon before label',isDisabled:- 'disabled (aria-disabled); skipped by arrows/typeahead, not focusable',+ 'disabled (aria-disabled); reached by arrows/typeahead, focusable, inert',endContent: 'content after label+description',ref: 'forwarded to the row root (the role="menuitemradio" element)',},diff --git a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsxindex a81615fb71..0820105be0 100644--- a/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx@@ -40,6 +40,7 @@ import {colorVars, focusVars, spacingVars} from '../theme/tokens.stylex';import {composeEventHandlers, mergeProps, themeProps} from '../utils';import type {BaseProps} from '../BaseProps';import {useDropdownMenuRadioGroupContext} from './DropdownMenuContext';+import {keepDisabledRowUnfocused} from './menuItemRoles';const styles = stylex.create({root: {@@ -111,9 +112,9 @@ export interface DropdownMenuRadioItemProps extends Omit<icon?: ReactNode | IconType;/*** Whether this individual radio item is disabled. A disabled item stays in- * the accessibility tree as disabled (`aria-disabled`) but takes no focus:- * the arrow keys, typeahead, and the pointer highlight skip it, and- * selection is blocked.+ * the accessibility tree as disabled (`aria-disabled`), and the arrow keys+ * and typeahead reach it so keyboard users find it. The pointer highlight+ * skips it, and selection is blocked.* @default false*/isDisabled?: boolean;@@ -189,9 +190,13 @@ export function DropdownMenuRadioItem({return (<Item{...rest}+ onMouseDown={composeEventHandlers(+ rest.onMouseDown,+ isDisabled ? keepDisabledRowUnfocused : undefined,+ )}role="menuitemradio"aria-checked={isChecked}- tabIndex={isDisabled ? undefined : -1}+ tabIndex={-1}onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}marker={// No wrapper — see DropdownMenuCheckboxItem: the target belongs on thediff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsxindex 2f30412fdc..3cd95703a2 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx@@ -412,6 +412,67 @@ describe('DropdownMenuSubMenu', () => {});});+describe('DropdownMenuSubMenu disabled rows', () => {+ it('the arrow keys reach a disabled sub-menu row and move past it', async () => {+ const user = userEvent.setup();+ render(+ <DropdownMenu button={{label: 'Actions'}}>+ <DropdownMenuItem label="Edit" onClick={() => {}} />+ <DropdownMenuSubMenu label="Move to" isDisabled>+ <DropdownMenuItem label="Projects" onClick={() => {}} />+ </DropdownMenuSubMenu>+ <DropdownMenuItem label="Print" onClick={() => {}} />+ </DropdownMenu>,+ );+ screen.getByRole('button', {name: /Actions/}).focus();+ await user.keyboard('{Enter}');+ const edit = screen.getByRole('menuitem', {name: 'Edit', hidden: true});+ await waitFor(() => expect(edit).toHaveFocus());+ const moveTo = screen.getByRole('menuitem', {+ name: /Move to/,+ hidden: true,+ });+ expect(moveTo).toHaveAttribute('tabindex', '-1');+ await user.keyboard('{ArrowDown}');+ expect(moveTo).toHaveFocus();+ await user.keyboard('{ArrowDown}');+ expect(+ screen.getByRole('menuitem', {name: 'Print', hidden: true}),+ ).toHaveFocus();+ });++ it('a keyboard open lands on the first enabled row, and ArrowUp then reaches the disabled one', async () => {+ const user = userEvent.setup();+ render(+ <DropdownMenu button={{label: 'Actions'}}>+ <DropdownMenuSubMenu label="Move to">+ <DropdownMenuItem label="Projects" isDisabled onClick={() => {}} />+ <DropdownMenuItem label="Archive" onClick={() => {}} />+ </DropdownMenuSubMenu>+ </DropdownMenu>,+ );+ await user.click(screen.getByRole('button', {name: /Actions/}));+ await waitFor(() => {+ expect(+ screen.getByRole('menu', {name: 'Actions', hidden: true}),+ ).toHaveFocus();+ });+ screen.getByRole('menuitem', {name: /Move to/, hidden: true}).focus();+ await user.keyboard('{ArrowRight}');+ await waitFor(() => {+ expect(+ screen.getByRole('menuitem', {name: 'Archive', hidden: true}),+ ).toHaveFocus();+ });+ await user.keyboard('{ArrowUp}');+ await waitFor(() => {+ expect(+ screen.getByRole('menuitem', {name: 'Projects', hidden: true}),+ ).toHaveFocus();+ });+ });+});+describe('DropdownMenuSubMenu host attributes', () => {async function openRoot(user: ReturnType<typeof userEvent.setup>) {await user.click(screen.getByRole('button', {name: /Actions/}));@@ -1561,6 +1622,28 @@ describe('DropdownMenuSubMenu drill-in on a phone', () => {expect(drilled).toBeInTheDocument();});+ it('a keyboard drill-in lands on the first enabled row after Back, and ArrowUp reaches the disabled one', async () => {+ stubCompactTouch(true);+ const user = userEvent.setup();+ render(+ <DropdownMenu button={{label: 'Actions'}}>+ <DropdownMenuSubMenu label="Move to">+ <DropdownMenuItem label="Projects" isDisabled onClick={() => {}} />+ <DropdownMenuItem label="Archive" onClick={() => {}} />+ </DropdownMenuSubMenu>+ </DropdownMenu>,+ );+ await user.click(screen.getByRole('button', {name: /Actions/}));+ fireEvent.keyDown(await waitFor(() => shownRow('Move to')), {+ key: 'Enter',+ });+ await waitFor(() => shownMenu('Move to'));+ await waitFor(() => expect(shownRow('Archive')).toHaveFocus());+ fireEvent.keyDown(document.activeElement!, {key: 'ArrowUp'});+ expect(shownRow('Projects')).toHaveFocus();+ expect(shownRow('Projects')).toHaveAttribute('aria-disabled', 'true');+ });+it('presentation="flyout" keeps the flyout on a phone and "drill-in" drills on a laptop', async () => {stubCompactTouch(true);const user = userEvent.setup();diff --git a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsxindex 806c1f570c..1069c1c748 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSubMenu.tsx@@ -67,7 +67,7 @@ import {moveRegionsTab} from './menuRegionStops';import {Item} from '../Item';import {useLayer} from '../Layer/useLayer';import {layerAnimations} from '../Layer/layerAnimations.stylex';-import {useListFocus} from '../hooks/useListFocus';+import {useInternalListFocus} from '../hooks/useListFocus';import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';import {useMenuHover} from '../hooks/useMenuHover';import {@@ -107,8 +107,10 @@ import type {BaseProps} from '../BaseProps';import {MENU_ITEM_ROLES,MENU_ITEM_SELECTOR,+ MENU_ROW_SELECTOR,MENU_BOUNDARY_SELECTOR,activateMenuItem,+ keepDisabledRowUnfocused,} from './menuItemRoles';import {DropdownMenuContext,@@ -671,8 +673,9 @@ export function DropdownMenuSubMenu(focusItem,ownsEvent,getItems,- } = useListFocus<HTMLDivElement>({- itemSelector: MENU_ITEM_SELECTOR,+ } = useInternalListFocus<HTMLDivElement>({+ itemSelector: MENU_ROW_SELECTOR,+ reachesDisabledItems: true,boundarySelector: MENU_BOUNDARY_SELECTOR,// Menus wrap.wrap: true,@@ -790,8 +793,15 @@ export function DropdownMenuSubMenu(}pendingViewFocusRef.current = null;const items = getItems();- // Back is the first row; a keyboard open lands on the first row after it.- const target = mode === 'first' ? (items[1] ?? items[0]) : null;+ // Back is the first row; a keyboard open lands on the first enabled row+ // after it. The keys reach a disabled row, but an open never starts there.+ const target =+ mode === 'first'+ ? (items.find(+ (item, index) =>+ index > 0 && item.getAttribute('aria-disabled') !== 'true',+ ) ?? items[0])+ : null;if (target != null) {target.focus({preventScroll: true});} else {@@ -1217,10 +1227,14 @@ export function DropdownMenuSubMenu(// state and wiring are set after them, and its own handlers run// before the caller's.{...rest}+ onMouseDown={composeEventHandlers(+ rest.onMouseDown,+ isDisabled ? keepDisabledRowUnfocused : undefined,+ )}ref={triggerRowRef}id={triggerId}role="menuitem"- tabIndex={isDisabled ? undefined : -1}+ tabIndex={-1}aria-haspopup={hasRegions ? 'dialog' : 'menu'}aria-expanded={isOpen}aria-controls={isOpen ? (hasRegions ? frameId : contentId) : undefined}diff --git a/packages/core/src/DropdownMenu/__tests__/DropdownMenuAudit.a11y.chromium.spec.ts b/packages/core/src/DropdownMenu/__tests__/DropdownMenuAudit.a11y.chromium.spec.tsindex 5693312501..e473ee3ff8 100644--- a/packages/core/src/DropdownMenu/__tests__/DropdownMenuAudit.a11y.chromium.spec.ts+++ b/packages/core/src/DropdownMenu/__tests__/DropdownMenuAudit.a11y.chromium.spec.ts@@ -132,13 +132,13 @@ const CASES: Case[] = ['disabled-row','with-disabled-items','keyboard-last-row',- 'Disabled — aria-disabled row, muted, skipped by focus',+ 'Disabled — aria-disabled row, muted, reached by focus',),c('disabled-row-dark','with-disabled-items','keyboard-last-row',- 'Disabled — aria-disabled row, muted, skipped by focus',+ 'Disabled — aria-disabled row, muted, reached by focus',{mode: 'dark'},),c(@@ -536,20 +536,12 @@ function assertClaimedState(}if (state.startsWith('disabled-row')) {expectAnchored();- const disabledIndexes = rows.flatMap((row, index) =>- row.disabled ? [index] : [],- );- const lastEnabled = rows.reduce(- (last, row, index) => (row.disabled ? last : index),- -1,- );- expect(disabledIndexes.length, `${state}: a disabled row`).toBeGreaterThan(- 0,+ expect(rows.at(-1)?.disabled, `${state}: a trailing disabled row`).toBe(+ true,);- // End lands on the last enabled row: the trailing disabled row is skipped.- expect(lastEnabled).toBeLessThan(rows.length - 1);- expect(observed.focusedRowIndex).toBe(lastEnabled);- expect(focusedRow?.disabled).toBe(false);+ // End lands on the last row: the keys reach the trailing disabled row.+ expect(observed.focusedRowIndex).toBe(rows.length - 1);+ expect(focusedRow?.disabled).toBe(true);return;}if (state.startsWith('destructive-row')) {diff --git a/packages/core/src/DropdownMenu/__tests__/DropdownMenuDisabledRow.a11y.browser.spec.ts b/packages/core/src/DropdownMenu/__tests__/DropdownMenuDisabledRow.a11y.browser.spec.tsnew file mode 100644index 0000000000..5dd8e024fa--- /dev/null+++ b/packages/core/src/DropdownMenu/__tests__/DropdownMenuDisabledRow.a11y.browser.spec.ts@@ -0,0 +1,96 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y scope core/DropdownMenu++/**+ * @file DropdownMenuDisabledRow.a11y.browser.spec.ts+ * @input The `Core/DropdownMenu` WithDisabledItems story in a built+ * Storybook, driven by real keyboard input in Chromium and WebKit.+ * @output Real-engine proof that a keyboard open lands on the first enabled+ * row, that ArrowDown and End reach the disabled row, which takes focus and+ * is exposed as a disabled menu item, and that Enter and Space on it do+ * nothing and leave the menu open, and that a mouse press leaves it+ * unfocused (component:DropdownMenu FR17, DEC-11; useMenuPress FR2).+ * @position Run with `pnpm test:a11y-contract`.+ */++import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++let storybook: StaticServer;+test.beforeAll(async () => {+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+});+test.afterAll(async () => {+ await storybook?.close();+});++async function openMenuFromKeyboard(page: Page): Promise<void> {+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-dropdownmenu--with-disabled-items&viewMode=story`,+ );+ const trigger = page.getByRole('button', {name: 'Actions'});+ await trigger.focus();+ await page.keyboard.press('Enter');+ await expect(page.getByRole('menuitem', {name: 'Edit'})).toBeFocused();+}++test('the arrow keys reach a disabled row, which is exposed as disabled', async ({+ page,+}) => {+ await openMenuFromKeyboard(page);+ await page.keyboard.press('ArrowDown');+ await page.keyboard.press('ArrowDown');+ const disabledRow = page.getByRole('menuitem', {+ name: 'Delete (disabled)',+ disabled: true,+ });+ await expect(disabledRow).toBeFocused();++ // ArrowDown wraps past it to the first row; End comes back to it.+ await page.keyboard.press('ArrowDown');+ await expect(page.getByRole('menuitem', {name: 'Edit'})).toBeFocused();+ await page.keyboard.press('End');+ await expect(disabledRow).toBeFocused();+});++test('Enter and Space on a disabled row do nothing and leave the menu open', async ({+ page,+}) => {+ await openMenuFromKeyboard(page);+ await page.keyboard.press('End');+ const disabledRow = page.getByRole('menuitem', {name: 'Delete (disabled)'});+ await expect(disabledRow).toBeFocused();+ await page.keyboard.press('Enter');+ await page.keyboard.press(' ');+ await expect(page.getByRole('menu')).toBeVisible();+ await expect(disabledRow).toBeFocused();+ await expect(page.getByRole('button', {name: 'Actions'})).toHaveAttribute(+ 'aria-expanded',+ 'true',+ );+});++test('a mouse press on a disabled row leaves it unfocused', async ({page}) => {+ await page.goto(+ `${storybook.origin}/iframe.html?id=core-dropdownmenu--with-disabled-items&viewMode=story`,+ );+ await page.getByRole('button', {name: 'Actions'}).click();+ const disabledRow = page.getByRole('menuitem', {name: 'Delete (disabled)'});+ await expect(disabledRow).toBeVisible();+ const box = await disabledRow.boundingBox();+ if (box == null) {+ throw new Error('the disabled row has no box');+ }+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);+ await page.mouse.down();+ await expect(disabledRow).not.toBeFocused();+ await page.mouse.up();+ await expect(disabledRow).not.toBeFocused();+ await expect(page.getByRole('menu')).toBeVisible();+});diff --git a/packages/core/src/DropdownMenu/menuItemRoles.ts b/packages/core/src/DropdownMenu/menuItemRoles.tsindex 570da61f1f..084342fd30 100644--- a/packages/core/src/DropdownMenu/menuItemRoles.ts+++ b/packages/core/src/DropdownMenu/menuItemRoles.ts@@ -2,7 +2,7 @@/*** @file menuItemRoles.ts- * @output Shared menu-item role set + focus selector + keyboard activation.+ * @output Shared menu-item role set, row selectors, and keyboard activation.* @position Internal; used by DropdownMenu and ContextMenu so their* roving-focus, typeahead, and Enter/Space activation stay in sync.*@@ -17,10 +17,20 @@ export const MENU_ITEM_ROLES: ReadonlySet<string> = new Set(['menuitemcheckbox',]);+/** The rows a press can act on: enabled rows only. */export const MENU_ITEM_SELECTOR: string = [...MENU_ITEM_ROLES].map(role => `[role="${role}"]:not([aria-disabled="true"])`).join(',');+/**+ * Every row, disabled rows included. The arrow keys, Home, End and type-ahead+ * visit a disabled row, so a keyboard user finds it and its reason; the row+ * stays inert.+ */+export const MENU_ROW_SELECTOR: string = [...MENU_ITEM_ROLES]+ .map(role => `[role="${role}"]`)+ .join(',');+/*** Boundary selector for a single menu level. A menu and its submenu flyouts* both use `role="menu"`, and flyouts render inline (native popover, not a@@ -73,3 +83,14 @@ export function activateMenuItem(}),);}++/**+ * A disabled row's `onMouseDown`. The row takes focus from the keys+ * (`tabindex="-1"`), so a mouse press would otherwise focus it and light it.+ * Cancelling the press's default keeps focus where it is.+ */+export function keepDisabledRowUnfocused(event: {+ preventDefault(): void;+}): void {+ event.preventDefault();+}diff --git a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx b/packages/core/src/NavMenu/NavHeadingMenu.test.tsxindex f857f95a11..8f4b117944 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenu.test.tsx@@ -348,6 +348,28 @@ describe('NavHeadingMenuItem', () => {});describe('keyboard navigation', () => {+ it('reaches a disabled row with the keys and type-ahead; the row stays inert', async () => {+ const user = userEvent.setup();+ const onArchive = vi.fn();+ render(+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Rename" />+ <NavHeadingMenuItem label="Archive" isDisabled onClick={onArchive} />+ <NavHeadingMenuItem label="Delete" />+ </NavHeadingMenu>,+ );+ const [rename, archive, del] = screen.getAllByRole('menuitem');+ rename.focus();+ fireEvent.keyDown(rename, {key: 'ArrowDown'});+ expect(archive).toHaveFocus();+ await user.keyboard('{Enter}');+ expect(onArchive).not.toHaveBeenCalled();+ fireEvent.keyDown(archive, {key: 'ArrowDown'});+ expect(del).toHaveFocus();+ fireEvent.keyDown(del, {key: 'a'});+ expect(archive).toHaveFocus();+ });+it('keeps arrow navigation when an item handler cancels', () => {const onKeyDown = vi.fn((event: KeyboardEvent) => event.preventDefault());render(@@ -495,7 +517,7 @@ describe('keyboard navigation', () => {expect(screen.getByRole('menuitem', {name: 'Paste'})).toHaveFocus();});- it('typeahead skips a disabled menuitem (menus-11)', () => {+ it('typeahead reaches a disabled menuitem, which stays discoverable', () => {render(<NavHeadingMenu><NavHeadingMenuItem label="Cut" />@@ -504,14 +526,10 @@ describe('keyboard navigation', () => {</NavHeadingMenu>,);const menu = screen.getByRole('menu');- // Typing "p" must land on the enabled "Paste special", never the disabled- // "Paste (disabled)" — the disabled item is excluded from the typeahead- // selector entirely.fireEvent.keyDown(menu, {key: 'p'});- expect(screen.getByRole('menuitem', {name: 'Paste special'})).toHaveFocus();expect(screen.getByRole('menuitem', {name: 'Paste (disabled)'}),- ).not.toHaveFocus();+ ).toHaveFocus();});});diff --git a/packages/core/src/NavMenu/NavHeadingMenu.tsx b/packages/core/src/NavMenu/NavHeadingMenu.tsxindex 1221eb142c..ecd02fa5d4 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenu.tsx@@ -17,7 +17,7 @@ import * as stylex from '@stylexjs/stylex';import {spacingVars} from '../theme/tokens.stylex';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';-import {useListFocus} from '../hooks/useListFocus';+import {useInternalListFocus} from '../hooks/useListFocus';import {useMenuPress} from '../hooks/useMenuPress';import {pressOnItemsOnly} from '../hooks/menuPressOnItems';import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';@@ -53,9 +53,12 @@ const sizeStyles = stylex.create({},});-/** The rows a press, a key or typeahead can reach. */+/** The rows a press can act on. */const ENABLED_ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"])';+/** The rows a key or typeahead visits: a disabled row too, which stays inert. */+const ROW_SELECTOR = '[role="menuitem"]';+export interface NavHeadingMenuProps extends BaseProps<HTMLDivElement> {ref?: React.Ref<HTMLDivElement>;/** Menu items (NavHeadingMenuItem, dividers, custom content). */@@ -116,8 +119,9 @@ export function NavHeadingMenu({// SideNavHeading) still lets a mouse released outside dismiss it.const dismissMenu = use(NavHeadingDismissContext)?.dismiss;- const {listRef, handleKeyDown, focusItem} = useListFocus({- itemSelector: ENABLED_ITEM_SELECTOR,+ const {listRef, handleKeyDown, focusItem} = useInternalListFocus({+ itemSelector: ROW_SELECTOR,+ reachesDisabledItems: true,onEscape: closeMenu,});@@ -131,14 +135,12 @@ export function NavHeadingMenu({});const hasOverflow = useMenuOverflow(listRef, children, true);- // First-character typeahead over the (enabled) menu items (menus-11).+ // First-character typeahead over the menu items, disabled ones included.const getMenuItems = useCallback((): HTMLElement[] =>listRef.current? Array.from(- listRef.current.querySelectorAll<HTMLElement>(- ENABLED_ITEM_SELECTOR,- ),+ listRef.current.querySelectorAll<HTMLElement>(ROW_SELECTOR),): [],[listRef],diff --git a/packages/core/src/NavMenu/NavHeadingMenuItem.tsx b/packages/core/src/NavMenu/NavHeadingMenuItem.tsxindex 4032c95d82..a4027996bb 100644--- a/packages/core/src/NavMenu/NavHeadingMenuItem.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenuItem.tsx@@ -23,6 +23,7 @@ import {typeScaleVars,radiusVars,} from '../theme/tokens.stylex';+import {composeEventHandlers} from '../utils/composeEventHandlers';import {mergeProps} from '../utils/mergeProps';import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';import type {BaseProps} from '../BaseProps';@@ -30,6 +31,7 @@ import {useNavHeadingMenuContext} from './NavMenuContext';import {useLinkComponent} from '../Link/useLinkComponent';import {themeProps} from '../utils/themeProps';import {isRenderable} from '../utils/isRenderable';+import {keepDisabledRowUnfocused} from '../DropdownMenu/menuItemRoles';const styles = stylex.create({root: {@@ -164,12 +166,14 @@ export function NavHeadingMenuItem({return (<Element{...restProps}+ onMouseDown={composeEventHandlers(+ restProps.onMouseDown,+ isDisabled ? keepDisabledRowUnfocused : undefined,+ )}ref={itemRef}role="menuitem"- // A disabled link row has no href, so without tabIndex it could not take- // focus at all. -1 keeps it focusable but out of the Tab order, as an- // enabled row is (spec:AST-085 FR1).- tabIndex={isDisabled && !href ? undefined : -1}+ // Every row, disabled included, takes focus but is not a Tab stop.+ tabIndex={-1}aria-disabled={isDisabled || undefined}href={isDisabled ? undefined : href}// A menu row is never a draggable link: a mouse press that slides todiff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex 19346e1f74..98e4c8311e 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -145,6 +145,15 @@ export interface InternalListFocusOptions extends UseListFocusOptions {* a context menu. Unset (the default): a plain `focus()`.*/focusFollowsLastInput?: boolean;+ /**+ * The arrow keys, Home, End and the Page keys visit a disabled item as they+ * visit any other item. The item must take focus (`tabindex="-1"`). Use it in+ * a menu, where a disabled row stays discoverable and inert. `focusFirst` and+ * `focusLast` still land on an enabled item, so an open from the keyboard+ * lands on a row that acts. Unset (the default): navigation skips disabled+ * items.+ */+ reachesDisabledItems?: boolean;}/**@@ -407,6 +416,7 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(tabStopOrder,hasCaretGuard = false,focusFollowsLastInput = false,+ reachesDisabledItems = false,} = options;const listRef = useRef<T>(null);@@ -461,17 +471,19 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>();/**- * Find the next enabled item index from `start`, moving by `step`, optionally- * wrapping. Returns -1 when no enabled item exists in range. Skipping+ * Find the next item index from `start` that `isSkipped` does not pass over+ * (by default, the next enabled item), moving by `step`, optionally+ * wrapping. Returns -1 when no such item exists in range. Skipping* disabled items here (rather than relying on the selector) keeps navigation* from stalling on an item whose `.focus()` silently no-ops.*/- const findEnabledIndex = useCallback(+ const findItemIndex = useCallback((items: HTMLElement[],start: number,step: 1 | -1,shouldWrap: boolean,+ isSkipped: (el: HTMLElement) => boolean = isItemDisabled,): number => {const count = items.length;if (count === 0) {@@ -486,7 +498,7 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(index = (index + count) % count;}const item = items[index];- if (item && !isItemDisabled(item)) {+ if (item && !isSkipped(item)) {return index;}index += step;@@ -496,6 +508,11 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>([isItemDisabled],);+ const isSkippedByKeys = useCallback(+ (el: HTMLElement): boolean => !reachesDisabledItems && isItemDisabled(el),+ [reachesDisabledItems, isItemDisabled],+ );+/*** Get the currently focused item index.*/@@ -606,26 +623,26 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(*/const focusFirst = useCallback((): boolean => {const items = getItems();- const index = findEnabledIndex(items, 0, 1, false);+ const index = findItemIndex(items, 0, 1, false);if (index !== -1) {focusIndex(items, index);return true;}return false;- }, [getItems, findEnabledIndex, focusIndex]);+ }, [getItems, findItemIndex, focusIndex]);/*** Focus the last enabled item. Returns true when an item was focused.*/const focusLast = useCallback((): boolean => {const items = getItems();- const index = findEnabledIndex(items, items.length - 1, -1, false);+ const index = findItemIndex(items, items.length - 1, -1, false);if (index !== -1) {focusIndex(items, index);return true;}return false;- }, [getItems, findEnabledIndex, focusIndex]);+ }, [getItems, findItemIndex, focusIndex]);/*** PageDown / PageUp: move to the last / first enabled item fully@@ -642,7 +659,7 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(}const currentIndex = getCurrentIndex();const enabledIndices = items- .map((item, index) => (isItemDisabled(item) ? -1 : index))+ .map((item, index) => (isSkippedByKeys(item) ? -1 : index)).filter(index => index !== -1);if (enabledIndices.length === 0) {return;@@ -704,7 +721,7 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(focusIndex(items, target);}},- [getItems, getCurrentIndex, isItemDisabled, focusIndex, focusFirst],+ [getItems, getCurrentIndex, isSkippedByKeys, focusIndex, focusFirst],);/**@@ -814,24 +831,30 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(prevFrom = nextFrom - 1;}- if (isNext) {- const next = findEnabledIndex(items, nextFrom, 1, wrap);- if (next !== -1) {- focusIndex(items, next);- }- } else if (isPrev) {- const prev = findEnabledIndex(items, prevFrom, -1, wrap);- if (prev !== -1) {- focusIndex(items, prev);- }- } else if (isHome) {- focusFirst();- } else if (isEnd) {- focusLast();- } else if (isPageDown) {+ if (isPageDown) {focusPage(1);} else if (isPageUp) {focusPage(-1);+ } else {+ let target: number;+ if (isNext) {+ target = findItemIndex(items, nextFrom, 1, wrap, isSkippedByKeys);+ } else if (isPrev) {+ target = findItemIndex(items, prevFrom, -1, wrap, isSkippedByKeys);+ } else if (isHome) {+ target = findItemIndex(items, 0, 1, false, isSkippedByKeys);+ } else {+ target = findItemIndex(+ items,+ items.length - 1,+ -1,+ false,+ isSkippedByKeys,+ );+ }+ if (target !== -1) {+ focusIndex(items, target);+ }}e.preventDefault();@@ -844,10 +867,9 @@ export function useInternalListFocus<T extends HTMLElement = HTMLElement>(hasHomeEnd,hasPaging,hasCaretGuard,- findEnabledIndex,+ findItemIndex,+ isSkippedByKeys,focusIndex,- focusFirst,- focusLast,focusPage,onEscape,ownsEvent,