@astryxdesign/core 0.7.0-canary.fe57f54 → 0.7.0

package/src/DropdownMenu/DropdownMenu.spec.md

@@ -17,6 +17,7 @@ verified_by:
     packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx,
     packages/core/src/DropdownMenu/__tests__/DropdownMenuDrillIn.a11y.chromium.spec.ts,
     packages/core/src/DropdownMenu/__tests__/MenuPress.a11y.chromium.spec.ts,
+    packages/core/src/DropdownMenu/__tests__/MenuHeaderFooter.a11y.chromium.spec.ts,
     packages/core/src/BottomSheet/BottomSheet.test.tsx,
     packages/core/src/List/List.test.tsx,
     packages/core/src/Indicator/Indicator.test.tsx,
@@ -85,35 +86,37 @@ Consumer migration instructions belong in consumer docs and release notes.
 ## Public concepts
 
 Consumer props, item shapes, subcomponents, and presentation policy remain
-documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Two component-local concepts are added, by DEC-2 and DEC-3; each keeps its
-released default.
+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. |
+| 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.           |
 
 ## 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                                                 |
+| 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                                                 |
 
 ### Allowed variation
 
@@ -261,21 +264,22 @@ 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` |
+| 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. |
 
 ## Decision log
 
@@ -440,3 +444,24 @@ The value is a number of pixels. Rejected: an arbitrary CSS length (`50vh`,
 `calc(...)`), which is product-shaped tuning on a shared component that
 `spec:AST-002` does not admit, and which lets a caller write a cap the
 viewport term cannot reason about.
+
+### DEC-8 — Controls beside the rows go in `header` and `footer`
+
+**Reference:** `component:DropdownMenu/DEC-8`
+**Decider:** `cixzhang`, 2026-10-11
+
+`role="menu"` admits only menu items, groups and separators. A filter field
+or a "Create" button placed among the rows makes the menu invalid to a screen
+reader, and makes the menu's key handling and press model fight the control.
+The control belongs beside the menu, not in it. `header` and `footer` place it
+there: in the same popover or sheet, outside the menu element. Outside the
+menu element, the menu never claims the control's keys or presses. Because
+`children` stay rows only, nothing can be placed between rows; the component
+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:
+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.