@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -231,13 +231,13 @@ export const docs = {
       name: 'header',
       type: 'ReactNode',
       description:
-        'Content above the rows and outside the menu itself — a filter field, a toggle. A menu holds only its rows, so a control that is not a row goes here or in `footer`, never among the rows. It keeps its own keys and presses; Tab moves from it into the menu, and Shift+Tab before its first control closes the menu. The bottom sheet shows it above the actions.',
+        'Content above the rows and outside the menu itself — a filter field, a toggle. A menu holds only its rows, so a control that is not a row goes here or in `footer`, never among the rows. It keeps its own keys and presses. With a header or footer the popover is a modal dialog around the menu: Tab and Shift+Tab move through the header, the menu and the footer and wrap at either end, and Escape closes. The bottom sheet shows it above the actions.',
     },
     {
       name: 'footer',
       type: 'ReactNode',
       description:
-        'Content below the rows and outside the menu itself — a "Create" button. Tab from the menu moves into it, and Tab past its last control closes the menu. The bottom sheet shows it below the actions.',
+        'Content below the rows and outside the menu itself — a "Create" button. Tab from the menu moves into it, and Tab past its last control wraps to the start of the dialog (see `header`). The bottom sheet shows it below the actions.',
     },
     {
       name: 'placement',

package/src/DropdownMenu/DropdownMenu.spec.md

@@ -89,34 +89,36 @@ Consumer props, item shapes, subcomponents, and presentation policy remain
 documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Three component-local concepts are added, by DEC-2, DEC-3 and DEC-8; each
 keeps its released default.
 
-| Concept           | Closed values or states                                  | Meaning                                                                                                                                                               | Availability by variant/orientation/state | Default  | Owner                    | Stability | Invalid-value behavior                              |
-| ----------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | ------------------------ | --------- | --------------------------------------------------- |
-| Menu height cap   | `menuMaxHeight`: a number of pixels                      | Lifts the 300px cap for a menu that must fit its rows; the viewport still bounds it.                                                                                  | Pointer presentation                      | `300px`  | `component:DropdownMenu` | stable    | Ignored by the touch sheet.                         |
-| Trigger source    | `button` (Button props) or `renderTrigger` (render prop) | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu. | Both presentations                        | `button` | `component:DropdownMenu` | stable    | Both given: `trigger` wins and a dev warning fires. |
-| Header and footer | `header`, `footer`: any React node                       | Content above and below the rows, beside the menu inside the same popover or sheet — never inside the `role="menu"` element.                                          | Both presentations                        | none     | `component:DropdownMenu` | stable    | A false or empty value renders no region.           |
+| Concept           | Closed values or states                                  | Meaning                                                                                                                                                                                          | Availability by variant/orientation/state | Default  | Owner                    | Stability | Invalid-value behavior                              |
+| ----------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------- | ------------------------ | --------- | --------------------------------------------------- |
+| Menu height cap   | `menuMaxHeight`: a number of pixels                      | Lifts the 300px cap for a menu that must fit its rows; the viewport still bounds it.                                                                                                             | Pointer presentation                      | `300px`  | `component:DropdownMenu` | stable    | Ignored by the touch sheet.                         |
+| Trigger source    | `button` (Button props) or `renderTrigger` (render prop) | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu.                            | Both presentations                        | `button` | `component:DropdownMenu` | stable    | Both given: `trigger` wins and a dev warning fires. |
+| Header and footer | `header`, `footer`: any React node                       | Content above and below the rows, beside the menu inside the same popover or sheet — never inside the `role="menu"` element. With either, the pointer popover is a modal dialog around the menu. | Both presentations                        | none     | `component:DropdownMenu` | stable    | A false or empty value renders no region.           |
 
 ## Behavioral and layout contract
 
-| ID                    | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Basis                                                                                                                                                                         | Draft review state                                                                |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| FR1                   | Every current render contains a Trigger button. Pointer presentation renders a Pointer menu surface with pointer-owned rows and optional pointer headings, dividers, indicators, and nested flyouts. Touch presentation renders a Touch sheet frame containing a Touch menu surface, Touch heading, Touch action list, and Touch action rows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, and tests                                                                                                                                               | Verified current behavior; no new behavior decided                                |
-| FR2                   | The six current local targets are `dropdown-menu`, `dropdown-menu-item`, `dropdown-menu-radio`, `dropdown-menu-section-heading`, `dropdown-menu-divider`, and `dropdown-menu-indicator-icon`; every target remains on its current painted element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source, docs, and tests                                                                                                                                               | Verified current inventory; no target change                                      |
-| FR3                   | Button owns the Trigger button, BottomSheet owns the Touch sheet frame, List owns the Touch action list and Touch action rows, Indicator owns checkbox chrome, and Icon owns ordinary rendered icons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and owner docs                                                                                                                                                 | Verified current delegation; no ownership change                                  |
-| FR4                   | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                                                                                                                                                      | Verified modality split; no target change                                         |
-| FR5                   | Both menu surfaces carry `data-astryx-menu-press` and follow `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 browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Trigger opening and keyboard navigation are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite                                                                                                 | Proposed; verified in jsdom and real Chromium                                     |
-| FR6                   | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite                                                                      | Proposed; verified in jsdom, pending owner review                                 |
-| FR7                   | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `component:DropdownMenu/DEC-3`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-3                               |
-| FR8                   | The Trigger button opens the pointer menu on a mouse press-down and on a finger held for the long-press delay, with the module's settle rule on the opening release; pressing the trigger of an open menu closes it without reopening in the same gesture; a tap and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite                                                                                  | Proposed; verified in jsdom, pending owner review                                 |
-| Trigger source        | `button` (Button props) or `renderTrigger` (render prop)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu.         | Both presentations                                                                | `button`             | `component:DropdownMenu` | stable | Both given: `trigger` wins and a dev warning fires.              |
-| FR9                   | With `renderTrigger`, the rendered control MUST carry `aria-haspopup`, `aria-expanded`, `aria-controls` and the `id` the menu's `aria-labelledby` points at, and MUST receive the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. `button` and `trigger` are mutually exclusive: both given, `trigger` wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's `aria-label` when given, else the control's accessible name, read as the menu opens.                                                                                                                                                                                                                                                                                                                                                                               | `component:DropdownMenu/DEC-2`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-2                               |
-| Row destination       | `href` (+ `target`, `rel`) on an action item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | The row's act is navigation: the row itself is the link (`family:navigation-destinations`).                                                                                   | Pointer action row and Touch action row, compound and data mode                   | none (an action row) | `component:DropdownMenu` | stable | Blocked schemes follow the family rule; a disabled row has none. |
-| FR10                  | An action row with `href` MUST render as one anchor carrying `role="menuitem"` (the pointer menu) or the touch sheet's link row, routed through `LinkProvider`; a plain click MUST run `onClick`, then close the menu (`hasCloseOnSelect`), then let the browser navigate; a modified click or middle click MUST be left to the browser and MUST NOT run `onClick`; Enter and Space MUST activate through a synthesized click that carries the key's modifiers. A disabled link row has no `href`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `component:DropdownMenu/DEC-2`; `family:navigation-destinations`                                                                                                              | Proposed; verified in jsdom; owner to confirm DEC-1                               |
-| Sub-menu presentation | `presentation` on a sub-menu row: `flyout`, `drill-in`, `adaptive`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Whether a sub-menu opens beside its row or replaces the menu's rows with its own and a Back row, in the same box. `adaptive` drills in when a coarse pointer opened the menu. | Pointer presentation, compound and data mode                                      | `adaptive`           | `component:DropdownMenu` | stable | An unknown value reads as `adaptive`.                            |
-| FR11                  | When a compact touch display opened the pointer menu (`COMPACT_TOUCH_PRESENTATION_QUERY`, the same query the root presentation uses for its bottom sheet, sampled once as it opens) an `adaptive` sub-menu row MUST drill in: its rows and a leading Back row named "Back to <parent>" replace the menu's rows in the same Pointer menu surface, no flyout opens, the drilled list is a `menu` named by the row's label, and Back, Escape and ArrowLeft MUST return to the row with focus on it; a pick inside closes the whole menu. Roving focus and typeahead scope to the shown rows; sibling rows and dividers need no knowledge of it. `presentation="flyout"` keeps the flyout; `"drill-in"` drills in on any pointer.                                                                                                                                                                                                                                                    | `component:DropdownMenu/DEC-2`; `architecture:interaction-modality`                                                                                                           | Proposed; verified in jsdom and Chromium (coarse pointer); owner to confirm DEC-5 |
-| FR12                  | In the pointer menu ArrowDown on the last enabled row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp move to the last and first fully visible enabled row and, pressed there again, one viewport further without wrapping; ArrowUp on the trigger opens with the last enabled row highlighted; the key that opened the menu and its auto-repeats do not activate; typeahead matches the row's label element alone and ignores Control/Command chords and input-method composition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Proposed in this change; `DropdownMenu.test.tsx` keyboard suite, `useListFocus.test.tsx`, `useTypeahead.test.tsx`                                                             | Proposed; verified in jsdom, pending owner review                                 |
-| FR13                  | On a mouse, a nested flyout stays open while the pointer is inside the triangle from where it left its row to the flyout's near edge — including while the pointer is paused there — and closes after the existing delay once the pointer has left both the row and that triangle. The row's click toggle and its guard window are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Proposed in this change; `DropdownMenuSubMenu.test.tsx` safe-triangle suite, `useMenuHover.test.tsx`                                                                          | Proposed; verified in jsdom, pending owner review                                 |
-| FR14                  | A compound `DropdownMenuGroup` is one `role="group"` named by its heading through `aria-labelledby`; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. An untitled group is an unnamed `role="group"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | DEC-1, docs, and tests                                                                                                                                                        | Proposed; awaiting owner approval                                                 |
-| FR15                  | With `header` or `footer`, the pointer popover holds the header, then the `role="menu"` element, then the footer, and the menu element holds only its rows. 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 from the menu moves to the footer, and Shift+Tab to the header, when that region holds a control Tab can reach; otherwise Tab closes the menu as before. Tab past the footer's last control or Shift+Tab before the header's first closes the menu, and focus returns to the trigger. From a row of an open sub-menu, Tab and Shift+Tab close every open flyout and continue as they do from a row of the root menu. Escape closes from anywhere in the popover. The bottom sheet shows the header above the actions and the footer below them. Without either, the menu renders and behaves exactly as it does without the props. | DEC-8, docs, and tests                                                                                                                                                        | Proposed; awaiting owner approval                                                 |
+| ID                    | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                                                                                                                                                                         | Draft review state                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| FR1                   | Every current render contains a Trigger button. Pointer presentation renders a Pointer menu surface with pointer-owned rows and optional pointer headings, dividers, indicators, and nested flyouts. Touch presentation renders a Touch sheet frame containing a Touch menu surface, Touch heading, Touch action list, and Touch action rows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source, docs, and tests                                                                                                                                               | Verified current behavior; no new behavior decided                                |
+| FR2                   | The six current local targets are `dropdown-menu`, `dropdown-menu-item`, `dropdown-menu-radio`, `dropdown-menu-section-heading`, `dropdown-menu-divider`, and `dropdown-menu-indicator-icon`; every target remains on its current painted element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source, docs, and tests                                                                                                                                               | Verified current inventory; no target change                                      |
+| FR3                   | Button owns the Trigger button, BottomSheet owns the Touch sheet frame, List owns the Touch action list and Touch action rows, Indicator owns checkbox chrome, and Icon owns ordinary rendered icons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Current source and owner docs                                                                                                                                                 | Verified current delegation; no ownership change                                  |
+| FR4                   | The same `dropdown-menu` target reaches the alternative Pointer menu surface and Touch menu surface. Pointer action rows retain `dropdown-menu-item`; touch action rows instead use List's `list-item` target.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests                                                                                                                                                      | Verified modality split; no target change                                         |
+| FR5                   | Both menu surfaces carry `data-astryx-menu-press` and follow `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 browser's stray click never acts, and the Pointer menu surface declares `touch-action` by overflow. Trigger opening and keyboard navigation are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `module:DropdownMenu/useMenuPress`; `DropdownMenu.test.tsx` press model suite                                                                                                 | Proposed; verified in jsdom and real Chromium                                     |
+| FR6                   | When the pointer menu closes, focus returns to the Trigger button with a visible ring only when the menu was driven by keyboard; a press outside that landed on a focusable control keeps focus there.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `architecture:interaction-modality` INV1; proposed in this change; `DropdownMenu.test.tsx` closing suite                                                                      | Proposed; verified in jsdom, pending owner review                                 |
+| FR7                   | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `component:DropdownMenu/DEC-3`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-3                               |
+| FR8                   | The Trigger button opens the pointer menu on a mouse press-down and on a finger held for the long-press delay, with the module's settle rule on the opening release; pressing the trigger of an open menu closes it without reopening in the same gesture; a tap and the keyboard open as before (`module:DropdownMenu/useMenuPress` proposed FR8, FR9).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Proposed `module:DropdownMenu/useMenuPress/DEC-4`; `DropdownMenu.test.tsx` press model suite                                                                                  | Proposed; verified in jsdom, pending owner review                                 |
+| Trigger source        | `button` (Button props) or `renderTrigger` (render prop)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Which control the menu hangs off. `trigger` receives `DropdownMenuTriggerProps` — the press model, keyboard opens, toggle click and ARIA wiring — and names the menu.         | Both presentations                                                                | `button`             | `component:DropdownMenu` | stable | Both given: `trigger` wins and a dev warning fires.              |
+| FR9                   | With `renderTrigger`, the rendered control MUST carry `aria-haspopup`, `aria-expanded`, `aria-controls` and the `id` the menu's `aria-labelledby` points at, and MUST receive the same press-model, keyboard-open and toggle-click handlers as the Button path; the menu is named by that control. `button` and `trigger` are mutually exclusive: both given, `trigger` wins and a dev warning fires, in both presentations. A drilled-in Back row (FR11) returns to the menu by that same name: the caller's `aria-label` when given, else the control's accessible name, read as the menu opens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `component:DropdownMenu/DEC-2`                                                                                                                                                | Proposed; verified in jsdom; owner to confirm DEC-2                               |
+| Row destination       | `href` (+ `target`, `rel`) on an action item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | The row's act is navigation: the row itself is the link (`family:navigation-destinations`).                                                                                   | Pointer action row and Touch action row, compound and data mode                   | none (an action row) | `component:DropdownMenu` | stable | Blocked schemes follow the family rule; a disabled row has none. |
+| FR10                  | An action row with `href` MUST render as one anchor carrying `role="menuitem"` (the pointer menu) or the touch sheet's link row, routed through `LinkProvider`; a plain click MUST run `onClick`, then close the menu (`hasCloseOnSelect`), then let the browser navigate; a modified click or middle click MUST be left to the browser and MUST NOT run `onClick`; Enter and Space MUST activate through a synthesized click that carries the key's modifiers. A disabled link row has no `href`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `component:DropdownMenu/DEC-2`; `family:navigation-destinations`                                                                                                              | Proposed; verified in jsdom; owner to confirm DEC-1                               |
+| Sub-menu presentation | `presentation` on a sub-menu row: `flyout`, `drill-in`, `adaptive`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Whether a sub-menu opens beside its row or replaces the menu's rows with its own and a Back row, in the same box. `adaptive` drills in when a coarse pointer opened the menu. | Pointer presentation, compound and data mode                                      | `adaptive`           | `component:DropdownMenu` | stable | An unknown value reads as `adaptive`.                            |
+| FR11                  | When a compact touch display opened the pointer menu (`COMPACT_TOUCH_PRESENTATION_QUERY`, the same query the root presentation uses for its bottom sheet, sampled once as it opens) an `adaptive` sub-menu row MUST drill in: its rows and a leading Back row named "Back to <parent>" replace the menu's rows in the same Pointer menu surface, no flyout opens, the drilled list is a `menu` named by the row's label, and Back, Escape and ArrowLeft MUST return to the row with focus on it; a pick inside closes the whole menu. Roving focus and typeahead scope to the shown rows; sibling rows and dividers need no knowledge of it. `presentation="flyout"` keeps the flyout; `"drill-in"` drills in on any pointer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `component:DropdownMenu/DEC-2`; `architecture:interaction-modality`                                                                                                           | Proposed; verified in jsdom and Chromium (coarse pointer); owner to confirm DEC-5 |
+| FR12                  | In the pointer menu ArrowDown on the last enabled row wraps to the first and ArrowUp on the first to the last; PageDown and PageUp move to the last and first fully visible enabled row and, pressed there again, one viewport further without wrapping; ArrowUp on the trigger opens with the last enabled row highlighted; the key that opened the menu and its auto-repeats do not activate; typeahead matches the row's label element alone and ignores Control/Command chords and input-method composition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Proposed in this change; `DropdownMenu.test.tsx` keyboard suite, `useListFocus.test.tsx`, `useTypeahead.test.tsx`                                                             | Proposed; verified in jsdom, pending owner review                                 |
+| FR13                  | On a mouse, a nested flyout stays open while the pointer is inside the triangle from where it left its row to the flyout's near edge — including while the pointer is paused there — and closes after the existing delay once the pointer has left both the row and that triangle. The row's click toggle and its guard window are unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Proposed in this change; `DropdownMenuSubMenu.test.tsx` safe-triangle suite, `useMenuHover.test.tsx`                                                                          | Proposed; verified in jsdom, pending owner review                                 |
+| FR14                  | A compound `DropdownMenuGroup` is one `role="group"` named by its heading through `aria-labelledby`; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. An untitled group is an unnamed `role="group"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | DEC-1, docs, and tests                                                                                                                                                        | Proposed; awaiting owner approval                                                 |
+| 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, docs, and tests                                                                                                                                                | Proposed; awaiting owner approval                                                 |
+| FR16                  | `DropdownMenuCheckboxItem` MUST expose one `menuitemcheckbox` row whose `aria-checked` equals its controlled value; enabled activation reports `!value`, stays open by default, and composes consumer click and pointer-move handlers with owned activation and hover focus. Disabled activation calls no consumer activation handler.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Released subcomponent API; `architecture:public-component-api/INV5–INV8`; `DropdownMenuSelectable.test.tsx`                                                                   | Verified current behavior; consumer handlers are preserved                        |
+| FR17                  | Disabled menu rows SHOULD remain keyboard-discoverable while activation stays blocked. Current shared `useListFocus` deliberately skips every `aria-disabled` row, including checkbox items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | WAI-ARIA Menu pattern; current shared navigation source/tests                                                                                                                 | Objective mismatch; shared mechanism remains undecided in OQ1                     |
 
 ### Allowed variation
 
@@ -166,6 +168,45 @@ visibility helper.
   carries `aria-labelledby` pointing at the control's `id` (the Button path
   keeps `aria-label`), and the control carries `aria-haspopup="menu"`,
   `aria-expanded` and `aria-controls`.
+- **AR2 — A row that navigates is a link element.** A row with an `href` is
+  the anchor itself: in the pointer menu it keeps `role="menuitem"` so the menu
+  stays one menu, while a modified click or Enter keeps the browser's link
+  meaning; in the bottom sheet the row is a plain link; a disabled link row is
+  not activatable.
+- **AR3 — A drilled-in sub-menu stays one menu.** On a compact touch display a
+  sub-menu replaces the rows in the same menu box with a "Back to <parent>" row
+  and its own rows; after a keyboard open focus lands on the first row after
+  Back, after a pointer open on the drilled list (the `menu`); Back, Escape, or
+  ArrowLeft return to the parent view with focus restored.
+- **AR4 — The anchored trigger adopts the APG Menu Button pattern's required
+  parts** (`spec:AST-020/FR15`): the control that opens the anchored pointer
+  menu is a `button` with an accessible name, `aria-haspopup="menu"`,
+  `aria-expanded` reflecting the menu, and `aria-controls` naming it; Enter or
+  Space opens the menu with focus on the first enabled row. As a named
+  exception under that rule, the trigger also opens on ArrowDown (focus on the
+  first enabled row) and ArrowUp (focus on the last enabled row), the keyboard
+  this component already ships. A `renderTrigger` control receives
+  `aria-haspopup`, `aria-expanded`, `aria-controls`, and the keyboard and focus
+  handlers through the spread props (FR9); the caller's control supplies its
+  own `button` role and accessible name. The bottom-sheet presentation and a
+  pointer menu with `header` or `footer` are outside this pattern: their
+  trigger opens a dialog and says `aria-haspopup="dialog"` (AR5).
+- **AR5 — With a header or footer, the pointer popover adopts the APG Dialog
+  (Modal) pattern's required parts** (`spec:AST-020/FR15`): `role="dialog"`,
+  `aria-modal="true"`, and an accessible name, the menu's; focus moves into
+  the dialog on open, to the menu or its first enabled row as FR6 and FR12
+  already state; Tab and Shift+Tab cycle within it (FR15); Escape closes it
+  and focus returns to the trigger. The menu inside keeps AR1–AR3. The
+  trigger keeps `aria-expanded`; its `aria-haspopup` says `dialog`, and its
+  `aria-controls` names the popover that holds the dialog rather than the
+  menu, as Popover's own trigger does.
+
+- **AR6 — Checkbox rows remain one control.** The row owns
+  `menuitemcheckbox`, its accessible name, checked state, focus, and activation;
+  Indicator's checkbox marker is decorative. Disabled activation is inert.
+  Current shared navigation skips disabled rows instead of making them
+  discoverable as the WAI-ARIA Menu pattern recommends; FR17 and OQ1 retain that
+  gap without inventing a component-local focus path.
 
 ## Design relationships
 
@@ -264,22 +305,25 @@ than adding a DropdownMenu-owned heading target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                 | Representative states                                                                                                                                                                                                                 | Mutation or failure expectation                                                                                                                                                        | Audit section                 |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1, FR4            | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites                                                                               | Root pointer, nested pointer, root touch, drill-in                                                                                                                                                                                    | Collapsing presentation-specific parts or owners fails structure, target, or role assertions.                                                                                          | `audit:DropdownMenu/anatomy`  |
-| FR2                 | DropdownMenu target suites, source inspection, and theming target inventories                                                                                                | All six local targets                                                                                                                                                                                                                 | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory.                                                                                       | `audit:DropdownMenu/theming`  |
-| FR3                 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests                                                                           | Trigger, touch actions, icons, checkbox, radio                                                                                                                                                                                        | A composed part loses its owner target or is documented as a new local target.                                                                                                         | `audit:DropdownMenu/theming`  |
-| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records                                                                    | Light dismiss, nested flyout, sheet dismissal                                                                                                                                                                                         | Documentation claims a shared owner where current source retains local behavior, or the reverse.                                                                                       | `audit:DropdownMenu/behavior` |
-| FR5                 | `DropdownMenu.test.tsx` press model suite; the module record's own map                                                                                                       | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker                                                                                                                                            | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails.                                                                            | `audit:DropdownMenu/behavior` |
-| FR6                 | `DropdownMenu.test.tsx` dismissal, closing and press model suites; `__tests__/MenuPress.a11y.chromium.spec.ts` in real Chromium                                              | keyboard/pointer dismissal, Escape after press-open, press outside on a control, pointer pick, closed menu                                                                                                                            | Focus left on the body after a pointer pick, on the control focused before a press-open, or a ring after pointer input, fails.                                                         | `audit:DropdownMenu/behavior` |
-| FR7                 | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it. | `component:DropdownMenu/DEC-3`                                                                                                                                                                                                        | Proposed; verified in jsdom; owner to confirm DEC-3                                                                                                                                    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                | Canonical anatomy and current target inventory                                                                                                                                                                                        | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation.                                                                                                  | `audit:DropdownMenu/theming`  |
-| FR8                 | `DropdownMenu.test.tsx` press model suite (trigger cases)                                                                                                                    | Press-open + drag-release, unsettled opening release, trigger toggle, held touch, tap                                                                                                                                                 | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails.                                                       | `audit:DropdownMenu/behavior` |
-| FR9                 | `DropdownMenu.test.tsx` custom trigger suite; `DropdownMenuSubMenu.test.tsx` custom-trigger Back row cases                                                                   | Icon button, chip, list row; open, toggle, keyboard open, name; drill-in Back row                                                                                                                                                     | A rendered control missing `aria-haspopup`, `aria-expanded` or `aria-controls`, an unnamed menu, a lost keyboard open, or a "Back to Menu" row, fails.                                 | `audit:DropdownMenu/anatomy`  |
-| FR8, AR2            | `DropdownMenu.test.tsx` "DropdownMenuItem href" suite (pointer menu and bottom sheet)                                                                                        | Plain click, ⌘-click, Enter with modifiers, disabled link row                                                                                                                                                                         | A row rendering an inner anchor, running `onClick` on a modified click, or a synthesized click dropping the modifiers fails.                                                           | `audit:DropdownMenu/behavior` |
-| FR12, AR3           | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" suite; `__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts` (real Chromium, coarse pointer)                            | Drill in, Back, Escape, ArrowLeft, nested level, scoped typeahead, forced presentations, close resets                                                                                                                                 | A flyout opening on a coarse pointer, a missing Back row, sibling rows staying in the order, or focus not returning to the row fails.                                                  | `audit:DropdownMenu/behavior` |
-| FR10                | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites                                                   | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows                                                                                                                            | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails.                          | `audit:DropdownMenu/behavior` |
-| FR15                | `DropdownMenu.test.tsx` header and footer suite; `__tests__/MenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium                                                         | regions outside the menu element, typing in a header field, Tab walk header → menu → footer → close, Tab and Shift+Tab from an open sub-menu, Escape from the header, a finger tap on a footer button, bottom sheet order, no regions | A region rendered inside the menu element, a header key taken by typeahead, a Tab that leaves the menu open with focus outside it, or a footer tap swallowed by the press model fails. |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Representative states                                                                                                                                                                                                                                                                                                                    | Mutation or failure expectation                                                                                                                                                                                                                                                                                                    | Audit section                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| FR1, FR4            | `DropdownMenu.test.tsx` pointer, bottom-sheet, adaptive, section, divider, and drill-in suites                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Root pointer, nested pointer, root touch, drill-in                                                                                                                                                                                                                                                                                       | Collapsing presentation-specific parts or owners fails structure, target, or role assertions.                                                                                                                                                                                                                                      | `audit:DropdownMenu/anatomy`                   |
+| FR2                 | DropdownMenu target suites, source inspection, and theming target inventories                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | All six local targets                                                                                                                                                                                                                                                                                                                    | Removing, renaming, or assigning a current target to the wrong part fails evidence or inventory.                                                                                                                                                                                                                                   | `audit:DropdownMenu/theming`                   |
+| FR3                 | `DropdownMenuSelectable.test.tsx` plus BottomSheet, List, Indicator, Icon, and Divider owner tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Trigger, touch actions, icons, checkbox, radio                                                                                                                                                                                                                                                                                           | A composed part loses its owner target or is documented as a new local target.                                                                                                                                                                                                                                                     | `audit:DropdownMenu/theming`                   |
+| Layer relationships | `DropdownMenu.test.tsx`, `DropdownMenuSubMenu.test.tsx`, and current layer/dismissal architecture records                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Light dismiss, nested flyout, sheet dismissal                                                                                                                                                                                                                                                                                            | Documentation claims a shared owner where current source retains local behavior, or the reverse.                                                                                                                                                                                                                                   | `audit:DropdownMenu/behavior`                  |
+| FR5                 | `DropdownMenu.test.tsx` press model suite; the module record's own map                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Finger slide across rows, outside release by mouse and finger, `touch-action`, root marker                                                                                                                                                                                                                                               | A row acting on the press or the stray click, a lost `touch-action`, or a finger release that closes fails.                                                                                                                                                                                                                        | `audit:DropdownMenu/behavior`                  |
+| FR6                 | `DropdownMenu.test.tsx` dismissal, closing and press model suites; `__tests__/MenuPress.a11y.chromium.spec.ts` in real Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                        | keyboard/pointer dismissal, Escape after press-open, press outside on a control, pointer pick, closed menu                                                                                                                                                                                                                               | Focus left on the body after a pointer pick, on the control focused before a press-open, or a ring after pointer input, fails.                                                                                                                                                                                                     | `audit:DropdownMenu/behavior`                  |
+| FR7                 | `menuMaxHeight` MUST replace the 300px term of the menu's and its popover viewport's block-size cap while the viewport gutters still bound both; the touch sheet ignores it.                                                                                                                                                                                                                                                                                                                                                                                           | `component:DropdownMenu/DEC-3`                                                                                                                                                                                                                                                                                                           | Proposed; verified in jsdom; owner to confirm DEC-3                                                                                                                                                                                                                                                                                |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Canonical anatomy and current target inventory                                                                                                                                                                                                                                                                                           | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation.                                                                                                                                                                                                                                              | `audit:DropdownMenu/theming`                   |
+| FR8                 | `DropdownMenu.test.tsx` press model suite (trigger cases)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Press-open + drag-release, unsettled opening release, trigger toggle, held touch, tap                                                                                                                                                                                                                                                    | A menu that does not open on a mouse press, an unsettled release that acts, or a trigger that reopens in the same gesture fails.                                                                                                                                                                                                   | `audit:DropdownMenu/behavior`                  |
+| FR9                 | `DropdownMenu.test.tsx` custom trigger suite; `DropdownMenuSubMenu.test.tsx` custom-trigger Back row cases                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Icon button, chip, list row; open, toggle, keyboard open, name; drill-in Back row                                                                                                                                                                                                                                                        | A rendered control missing `aria-haspopup`, `aria-expanded` or `aria-controls`, an unnamed menu, a lost keyboard open, or a "Back to Menu" row, fails.                                                                                                                                                                             | `audit:DropdownMenu/anatomy`                   |
+| AR4                 | `DropdownMenu.test.tsx` cases "has aria-haspopup and aria-expanded attributes", "keyboard open via Enter focuses the first enabled item", "walks into a mounted-open menu with ArrowDown from the focused trigger", "keyboard open via ArrowDown skips a disabled leading item", "ArrowUp on the trigger opens with the last row highlighted", and "a custom trigger opens from the keyboard and lands on the first row"; Space opening and `aria-controls` under the Menu Button accessibility contract (`internal/a11y-spec`, pending) bound to the anchored trigger | Button and `renderTrigger` controls; closed/open; Enter, Space, ArrowDown, ArrowUp open                                                                                                                                                                                                                                                  | The trigger loses its name, `aria-haspopup="menu"`, `aria-expanded` or `aria-controls`; a keyboard open lands focus somewhere other than the first (or, for ArrowUp, last) enabled row                                                                                                                                             | `audit:DropdownMenu/accessibility`             |
+| FR8, AR2            | `DropdownMenu.test.tsx` "DropdownMenuItem href" suite (pointer menu and bottom sheet)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Plain click, ⌘-click, Enter with modifiers, disabled link row                                                                                                                                                                                                                                                                            | A row rendering an inner anchor, running `onClick` on a modified click, or a synthesized click dropping the modifiers fails.                                                                                                                                                                                                       | `audit:DropdownMenu/behavior`                  |
+| FR12, AR3           | `DropdownMenuSubMenu.test.tsx` "drill-in on a phone" suite; `__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts` (real Chromium, coarse pointer)                                                                                                                                                                                                                                                                                                                                                                                                                      | Drill in, Back, Escape, ArrowLeft, nested level, scoped typeahead, forced presentations, close resets                                                                                                                                                                                                                                    | A flyout opening on a coarse pointer, a missing Back row, sibling rows staying in the order, or focus not returning to the row fails.                                                                                                                                                                                              | `audit:DropdownMenu/behavior`                  |
+| FR10                | `DropdownMenuSubMenu.test.tsx` safe-triangle suite; `useMenuHover.test.tsx` `isPointInSafeTriangle` and click-guard suites                                                                                                                                                                                                                                                                                                                                                                                                                                             | diagonal path toward the flyout, a pause inside it, path away, click-opened and hover-opened guard windows                                                                                                                                                                                                                               | A flyout that closes while the pointer is inside the triangle or paused in it, one that never closes after leaving it, or a changed guard-window rule, fails.                                                                                                                                                                      | `audit:DropdownMenu/behavior`                  |
+| FR15                | `DropdownMenu.test.tsx` header and footer suite; `__tests__/MenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium                                                                                                                                                                                                                                                                                                                                                                                                                                                   | dialog role, modality, name and trigger wiring; regions outside the menu element; typing in a header field; Tab walk header → menu → footer with wrap at both ends; Tab and Shift+Tab from an open sub-menu; hidden and hidden-wrapper controls; Escape from the header; a finger tap on a footer button; bottom sheet order; no regions | A region rendered inside the menu element, a popover with regions that is not a named modal dialog, a trigger still saying `aria-haspopup="menu"` with regions, a header key taken by typeahead, a Tab that leaves the dialog or closes it, focus stranded outside the dialog, or a footer tap swallowed by the press model fails. |
+| FR16                | `DropdownMenuSelectable.test.tsx`, source inspection, scoped `pr-a11y` over the `a11y/Checkbox pattern` stories, and owned Storybook states                                                                                                                                                                                                                                                                                                                                                                                                                            | checked, unchecked, disabled, caller click/pointer handlers, marker size and ownership                                                                                                                                                                                                                                                   | A dropped consumer handler, wrong checked state, nested semantic checkbox, disabled activation, or menu that closes by default fails.                                                                                                                                                                                              | `audit:DropdownMenuCheckboxItem/behavior`      |
+| FR17, AR6           | Shared navigation source and DropdownMenu keyboard tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | disabled checkbox row first, middle, and last                                                                                                                                                                                                                                                                                            | Current tests prove the shared hook skips the row; no keyboard-discoverability proof exists until OQ1 is settled.                                                                                                                                                                                                                  | `audit:DropdownMenuCheckboxItem/accessibility` |
 
 ## Decision log
 
@@ -365,7 +409,13 @@ breaks focus return.
 
 ## Open questions
 
-None.
+- **OQ1 — Which shared owner should make disabled menu rows keyboard-discoverable
+  without changing disabled behavior in non-menu composites?** (`human-api`)
+  WAI-ARIA's Menu pattern keeps disabled menu items focusable but inert. Current
+  `useListFocus` deliberately skips every `aria-disabled` item for all consumers,
+  and DropdownMenu's enabled-only focus-on-open and navigation tests depend on
+  that result. The requirement is objective; choosing a menu-specific hook policy
+  or a DropdownMenu-owned path changes a shared API and ownership boundary.
 
 ## Content boundary
 
@@ -391,7 +441,7 @@ and the router's prefetch; an inner anchor — two controls in one row.
 
 ## Open questions
 
-None.
+OQ1 above remains the only open question.
 
 ## Content boundary
 
@@ -460,8 +510,34 @@ menu element, the menu never claims the control's keys or presses. Because
 needs no inspection of its children to keep that true.
 
 The menu becomes one Tab stop between the regions, so the popover reads as
-one Tab sequence: header, menu, footer. Leaving it past either end closes the
-menu, as Tab from the rows always has. Focus on open is unchanged. Rejected:
+one Tab sequence: header, menu, footer, inside the dialog of DEC-10. Focus on
+open is unchanged. Rejected:
 letting the menu's handlers step aside for controls placed among the rows —
 that makes invalid structure work instead of fixing it; and a caller-wrapped
 items element, which leaves "nothing between the rows" to convention.
+
+### DEC-9 — The trigger is a Menu Button, arrow-key opening included
+
+**Reference:** `component:DropdownMenu/DEC-9`
+**Decider:** `cixzhang`, `2026-10-13`
+
+The pointer trigger already plays the Menu Button's role, so it carries the pattern's required parts (AR4). ArrowDown and ArrowUp opening go beyond the adoption rule's required set and stay as a named exception because the component shipped them (FR12 keeps the wrap once the menu is open) and removing a working keyboard path would cost the users who have it. ContextMenu and NavMenu are not covered by this decision.
+
+Rejected: dropping arrow-key opening to match the rule's default; adopting the pattern for every control that opens any layer.
+
+### DEC-10 — A popover with a header or footer is a modal dialog, and Tab wraps
+
+**Reference:** `component:DropdownMenu/DEC-10`
+**Decider:** `cixzhang`, 2026-10-13
+
+A popover that holds a menu and controls that are not menu items is not a
+menu: a trigger exposing `aria-haspopup="menu"` promises a menu, and the
+popover then holds a field or a button that is not one. With `header` or
+`footer`, the popover is therefore exposed as a named modal dialog with the
+menu inside it, the trigger says `aria-haspopup="dialog"`, and
+`aria-controls` names the popover that holds the dialog. Moving the
+menu role inward keeps every row a menu item and every other control outside
+the menu. Tab and Shift+Tab wrap within the dialog, as the APG Dialog
+pattern requires; Escape and a press outside close it. Without either prop
+the component is unchanged: a Menu Button whose Tab closes the menu. Rejected:
+closing on Tab past either end, which leaves a modal dialog by Tab.