@astryxdesign/core 0.7.3-canary.b74cf21 → 0.7.3-canary.cb489ff

package/src/CheckboxInput/CheckboxInput.tsx

@@ -19,7 +19,6 @@
 import {
   useId,
   useCallback,
-  use,
   useOptimistic,
   useRef,
   useTransition,
@@ -52,7 +51,6 @@ import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
-import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 
@@ -354,21 +352,10 @@ export function CheckboxInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the checkbox row (which already exists) and the
-  // native checkbox stays perceivable via aria-disabled instead of the disabled
-  // attribute. Value mutation is blocked by the isDisabled guard in onChange.
+  // A disabled checkbox stays focusable via aria-disabled instead of the
+  // native disabled attribute (spec:AST-085 FR1). Value mutation is blocked by
+  // the click and onChange guards on the input.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
-  // Keep the native checkbox focusable via aria-disabled either when it renders
-  // its own reason tooltip, or when it sits in a CheckboxList whose whole-group
-  // `disabledMessage` (shown on the group container) needs each checkbox to
-  // stay keyboard-perceivable. The group signals this through context rather
-  // than a public prop.
-  const checkboxListContext = use(CheckboxListContext);
-  const isFocusableDisabled =
-    isDisabled &&
-    (showsDisabledMessage ||
-      (checkboxListContext?.hasDisabledMessage ?? false));
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container row is not naturally focusable; focusin bubbles up from the
@@ -384,7 +371,7 @@ export function CheckboxInput({
   // `opacity: 0`, and only the indicator's own element can shape the outline
   // to match it. See useIndicatorFocusRing.
   const indicatorRef = useRef<HTMLSpanElement>(null);
-  const {focusProps} = useIndicatorFocusRing(indicatorRef, isDisabled);
+  const {focusProps} = useIndicatorFocusRing(indicatorRef);
 
   const isIndeterminate = optimisticValue === 'indeterminate';
   const isChecked = optimisticValue === true;
@@ -471,22 +458,25 @@ export function CheckboxInput({
             )}
             id={id}
             type="checkbox"
-            // Withhold the name while disabled: with a disabledMessage the
-            // input stays focusable (not natively disabled), and a disabled
-            // control must not submit.
+            // Withhold the name while disabled: the input stays focusable (not
+            // natively disabled), and a disabled control must not submit.
             name={isDisabled ? undefined : htmlName}
             checked={isChecked}
-            // With a disabledMessage the checkbox keeps focusability via
-            // aria-disabled so the reason is focus-discoverable; toggling is
-            // still blocked by the isDisabled guard in onChange below.
-            disabled={isDisabled && !isFocusableDisabled}
-            aria-disabled={isFocusableDisabled ? 'true' : undefined}
-            form={isFocusableDisabled ? '' : undefined}
+            aria-disabled={isDisabled ? 'true' : undefined}
+            // Detached from its form while disabled, so it neither submits nor
+            // blocks submission through `required` (spec:AST-085 FR3).
+            form={isDisabled ? '' : undefined}
+            // Native `disabled` suppressed onClick (FR2); preventDefault here
+            // would desync React's controlled checked state.
+            onClick={isDisabled ? undefined : rest.onClick}
             readOnly={isReadOnly}
             required={isRequired}
             aria-required={isEffectivelyRequired ? 'true' : undefined}
             onChange={e => {
               if (isDisabled || isBusy || isReadOnly) {
+                // Activation clears the native mixed state; React restores
+                // only `checked`, so restore `indeterminate` too.
+                e.target.indeterminate = isIndeterminate;
                 return;
               }
               const checked = e.target.checked;

package/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts

@@ -125,8 +125,8 @@ export const CHECKBOX_BINDING_STATES = [
   {
     id: 'input-disabled',
     binding: 'CheckboxInput',
-    summary: 'a natively disabled checkbox outside the tab sequence',
-    facts: facts({operable: false, focusable: false, disabled: true}),
+    summary: 'a disabled checkbox that keeps its tab stop',
+    facts: facts({operable: false, focusable: true, disabled: true}),
     visibleLabel: 'Managed setting',
     storyId: 'a11y-checkbox-pattern--input-disabled',
   },
@@ -269,7 +269,7 @@ export const CHECKBOX_BINDING_STATES = [
     id: 'list-item-disabled',
     binding: 'CheckboxListItem',
     summary: 'an individually disabled list item',
-    facts: facts({operable: false, focusable: false, disabled: true}),
+    facts: facts({operable: false, focusable: true, disabled: true}),
     visibleLabel: 'SMS',
     visibleLabelSelector: '[data-a11y-visible-label]',
     storyId: 'a11y-checkbox-pattern--list-item-disabled',

package/src/CheckboxList/CheckboxList.test.tsx

@@ -288,8 +288,9 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
     const checkboxes = screen.getAllByRole('checkbox');
-    expect(checkboxes[0]).toBeDisabled();
-    expect(checkboxes[1]).toBeDisabled();
+    expect(checkboxes[0]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[1]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[0]).not.toHaveAttribute('disabled');
   });
 
   it('does not call onChange when group is disabled', () => {
@@ -317,8 +318,9 @@ describe('CheckboxList', () => {
       </CheckboxList>,
     );
     const checkboxes = screen.getAllByRole('checkbox');
-    expect(checkboxes[0]).not.toBeDisabled();
-    expect(checkboxes[1]).toBeDisabled();
+    expect(checkboxes[0]).not.toHaveAttribute('aria-disabled');
+    expect(checkboxes[1]).toHaveAttribute('aria-disabled', 'true');
+    expect(checkboxes[1]).not.toHaveAttribute('disabled');
   });
 
   it('throws when item has no value prop inside collection-mode CheckboxList', () => {
@@ -1137,7 +1139,7 @@ describe('CheckboxListItem ARIA props', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('keeps checkboxes natively disabled when disabled without a reason', () => {
+    it('keeps checkboxes focusable via aria-disabled when disabled without a reason', () => {
       render(
         <CheckboxList
           label="Notifications"
@@ -1149,7 +1151,8 @@ describe('CheckboxListItem ARIA props', () => {
         </CheckboxList>,
       );
       for (const checkbox of screen.getAllByRole('checkbox', h)) {
-        expect(checkbox).toBeDisabled();
+        expect(checkbox).not.toHaveAttribute('disabled');
+        expect(checkbox).toHaveAttribute('aria-disabled', 'true');
       }
     });
   });

package/src/ContextMenu/ContextMenu.test.tsx

@@ -24,6 +24,7 @@ import {
   ContextMenuRadioItem,
 } from './index';
 import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
+import {DropdownMenuSubMenu} from '../DropdownMenu/DropdownMenuSubMenu';
 import {Divider} from '../Divider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
@@ -706,6 +707,46 @@ describe('ContextMenu dividers', () => {
 });
 
 describe('ContextMenu compound mode', () => {
+  it('shows a sub-menu with a header or footer as its rows alone, and says why in development', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      render(
+        <ContextMenu
+          menuContent={
+            <>
+              <DropdownMenuItem label="Rename" onClick={() => {}} />
+              <DropdownMenuSubMenu
+                label="Labels"
+                header={<input aria-label="Filter labels" />}
+                footer={<button type="button">Create label</button>}>
+                <DropdownMenuItem label="Bug" onClick={() => {}} />
+              </DropdownMenuSubMenu>
+            </>
+          }>
+          <div>Right-click me</div>
+        </ContextMenu>,
+      );
+      fireEvent.contextMenu(screen.getByText('Right-click me'));
+      const row = screen.getByRole('menuitem', {name: /Labels/, hidden: true});
+      // No region can sit outside this menu, so none renders inside it.
+      expect(row).toHaveAttribute('aria-haspopup', 'menu');
+      fireEvent.click(row, {detail: 1});
+      await waitFor(() => expect(row).toHaveAttribute('aria-expanded', 'true'));
+      expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+      expect(
+        screen.queryByRole('textbox', {name: 'Filter labels', hidden: true}),
+      ).toBeNull();
+      expect(
+        screen.getByRole('menuitem', {name: 'Bug', hidden: true}),
+      ).toBeInTheDocument();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('DropdownMenuSubMenu: header and footer'),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it('renders menuContent as menu items', () => {
     render(
       <ContextMenu

package/src/DropdownMenu/DropdownMenu.spec.md

@@ -86,7 +86,7 @@ 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. Three component-local concepts are added, by DEC-2, DEC-3 and DEC-8; each
+documented in `DropdownMenu.doc.mjs` and the subcomponent docs. Four component-local concepts are added, by DEC-2, DEC-3, DEC-8 and proposed DEC-13; each
 keeps its released default.
 
 | Concept           | Closed values or states                                  | Meaning                                                                                                                                                                                          | Availability by variant/orientation/state | Default  | Owner                    | Stability | Invalid-value behavior                              |
@@ -94,6 +94,7 @@ keeps its released default.
 | 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.           |
+| Sub-menu regions  | `header`, `footer` on a sub-menu: any React node         | Content above and below a sub-menu's rows, beside its menu inside its own surface; with either, that surface is a modal dialog named by the row (proposed FR20).                                 | Popover presentation                      | none     | `component:DropdownMenu` | proposed  | A false or empty value renders no region.           |
 
 ## Behavioral and layout contract
 
@@ -119,6 +120,7 @@ keeps its released default.
 | 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                     |
+| FR20                  | With `header` or `footer` on a sub-menu (`DropdownMenuSubMenu`), its surface is a modal dialog named by its row (AR7), holding the header, the sub-menu's `role="menu"` (rows only), then the footer. It sits in a host `DropdownMenu` renders beside its menu, never inside a menu; under a root with no such host (`ContextMenu`) the sub-menu shows its rows alone. On a fine pointer the dialog is the flyout; on a compact touch display, the drilled-in view, which replaces the root's menu and regions until popped. A region keeps its own keys and presses. The rows are one Tab stop: Tab and Shift+Tab walk the header's controls, the rows, then the footer's, and wrap; from a deeper flyout, that flyout closes and the walk goes on from the rows. An open lands as for any sub-menu (FR11, FR12), not on a region. Escape in the dialog, outside an IME composition and unless a control there handled it, returns focus to the row and leaves the root open. A pointer leaving the flyout keeps it open until focus leaves, and it closes with the flyout holding its row. Without either prop nothing changes.                                                                                                    | Proposed DEC-13; FR15; AR5                                                                                                                                                    | Proposed; verified in jsdom and Chromium, pending owner review                    |
 
 ### Allowed variation
 
@@ -200,13 +202,20 @@ visibility helper.
   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.
+- **AR7 (proposed) — A sub-menu with a header or footer adopts the same APG
+  Dialog (Modal) parts for its own surface** (`spec:AST-020/FR15`):
+  `role="dialog"`, `aria-modal="true"`, and an accessible name, its row's;
+  focus moves into the dialog on open, to the sub-menu's first row or its
+  menu as FR11 and FR12 already state; Tab and Shift+Tab cycle within it
+  (FR20); Escape closes it and focus returns to the row. The sub-menu's menu
+  inside keeps AR3. The row keeps `aria-expanded`; its `aria-haspopup` says
+  `dialog` and its `aria-controls` names the dialog.
 
 ## Design relationships
 
@@ -324,6 +333,7 @@ than adding a DropdownMenu-owned heading target.
 | 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` |
+| FR20, AR7           | `DropdownMenuSubMenu.test.tsx` "header and footer" suite; `ContextMenu.test.tsx` rows-alone case; `__tests__/SubMenuHeaderFooter.a11y.chromium.spec.ts` in real Chromium (fine pointer, coarse pointer)                                                                                                                                                                                                                                                                                                                                                                | flyout and phone view; dialog role, name, row wiring; regions outside menus; Tab walk and wrap from a field, row, deeper flyout; field keys, presses; Escape, IME and handled Escapes; keyboard open; pointer leaving, focus in then out; parent closing a nested flyout; view tracking its regions; ContextMenu rows alone              | A region inside a menu element, a surface with regions that is not a named modal dialog, a row still saying `aria-haspopup="menu"`, a field key taken by the menu, a Tab that leaves or closes the dialog, a flyout closed under focus by a pointer leaving, a flyout outliving its parent, or the root menu beside a view, fails. | `audit:DropdownMenu/behavior`                  |
 
 ## Decision log
 
@@ -541,3 +551,24 @@ 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.
+
+### DEC-13 (proposed) — A sub-menu's header and footer make its surface a dialog beside the menu
+
+**Reference:** `component:DropdownMenu/DEC-13`
+**Decider:** proposed by `vjeux`, 2026-10-14; pending owner review
+
+A filter field above a sub-menu's rows, or a door below them, is a control
+that is not a menu item, so DEC-8 and DEC-10 apply to the sub-menu's own
+surface as they apply to the root's: the sub-menu's menu holds only its rows,
+and the surface around it is a named modal dialog whose Tab order wraps. A
+flyout renders inside the menu that holds its row, so a dialog there would
+still sit inside that menu; the `DropdownMenu` therefore renders a host beside its menu,
+inside its popover, and a sub-menu with regions renders its surface there (the
+flyout layer, or the drilled-in view, which then takes the root menu's place).
+Rendered there, a flyout no longer hides with the flyout that holds its row,
+so it closes with it. The pointer leaving that flyout does not close it while
+focus is inside, because what was typed into its field would go with it.
+Rejected: regions inside the flyout beside the sub-menu's menu,
+which puts them inside the parent menu; a separate DropdownMenu for the level,
+which loses the row, the drill-in and the single press model; and closing the
+flyout when the pointer leaves it as any flyout does.

package/src/DropdownMenu/DropdownMenu.tsx

@@ -61,7 +61,10 @@ import {
 import {
   DropdownMenuContext,
   DropdownMenuRootOpenContext,
+  DropdownMenuSurfaceContext,
   type DropdownMenuContextValue,
+  type DropdownMenuSurfaceHost,
+  type DropdownMenuSurfaceValue,
 } from './DropdownMenuContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {useListFocus} from '../hooks/useListFocus';
@@ -112,6 +115,14 @@ const MENU_MAX_BLOCK_SIZE = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBloc
 const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`;
 const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
 
+// A sub-menu's drilled-in view with a header or footer renders in the surface
+// host that follows the menu, as the frame marked
+// `data-astryx-submenu-regions="view"` (hidden while a deeper view shows).
+// While one shows, the menu and its header and footer step aside. The rule
+// reads that from the DOM, so no state mirrors which view shows.
+const STEPS_ASIDE_FOR_VIEW =
+  ':has(~ * > [data-astryx-submenu-regions="view"]:not([hidden]))';
+
 const styles = stylex.create({
   triggerOpen: {
     backgroundImage: MENU_TRIGGER_OPEN_BACKGROUND,
@@ -125,7 +136,12 @@ const styles = stylex.create({
   },
   dropdown: {
     boxSizing: 'border-box',
-    display: 'flex',
+    display: {
+      default: 'flex',
+      // A sub-menu's drilled-in view with a header or footer shows in its
+      // place (see `stepsAsideForView`).
+      [STEPS_ASIDE_FOR_VIEW]: 'none',
+    },
     flexDirection: 'column',
     gap: spacingVars['--spacing-0-5'],
     // Pointer opens focus this container so subsequent arrow keys and Escape
@@ -175,6 +191,22 @@ const styles = stylex.create({
     flexShrink: 1,
     minBlockSize: 0,
   },
+  // Where a sub-menu with a header or footer renders its surface: beside the
+  // menu, never inside it. It owns no box, so the popover's layout is
+  // unchanged.
+  surfaceHost: {
+    display: 'contents',
+  },
+  // While a sub-menu's drilled-in view with its own header or footer shows
+  // in the surface host, the header and footer step aside for it, as the menu
+  // does (see `dropdown`). Derived from the DOM by the rule itself: the view
+  // is the frame in the host that is not hidden.
+  stepsAsideForView: {
+    display: {
+      default: null,
+      [STEPS_ASIDE_FOR_VIEW]: 'none',
+    },
+  },
   region: {
     flexShrink: 0,
     padding: spacingVars['--spacing-1'],
@@ -1455,12 +1487,39 @@ function DropdownMenuPopover({
 
   // The drill-in view stack for sub-menus on a phone.
   const {drillIn, wrapContent} = useMenuDrillIn(isOpen);
+  // The surface host is owned through a ref. State keeps only a key that
+  // changes whenever a host element attaches, the host included when it
+  // moves (a header or footer coming or going), so sub-menus re-render into
+  // the element that is mounted.
+  const surfaceHostRef = useRef<HTMLDivElement | null>(null);
+  const [surfaceHostKey, setSurfaceHostKey] = useState(0);
+  const attachSurfaceHost = useCallback((node: HTMLDivElement | null) => {
+    surfaceHostRef.current = node;
+    if (node != null) {
+      setSurfaceHostKey(key => key + 1);
+    }
+  }, []);
+  const surfaceHost = useMemo<DropdownMenuSurfaceHost>(
+    () => ({
+      getElement: () => (surfaceHostKey > 0 ? surfaceHostRef.current : null),
+    }),
+    [surfaceHostKey],
+  );
   const resolvedMaxHeight = menuMaxHeight == null ? null : `${menuMaxHeight}px`;
   // Context for compound items
   const contextValue = useMemo<DropdownMenuContextValue>(
     () => ({closeMenu, menuSize, drillIn, menuLabel}),
     [closeMenu, menuSize, drillIn, menuLabel],
   );
+  // What a sub-menu with a header or footer needs, on an internal context.
+  const surfaceValue = useMemo<DropdownMenuSurfaceValue>(
+    () => ({
+      host: surfaceHost,
+      ownerId: menuId,
+      menuMaxHeight: resolvedMaxHeight ?? undefined,
+    }),
+    [surfaceHost, menuId, resolvedMaxHeight],
+  );
 
   // Resolve menu content: data-driven items become components
   const menuContent = wrapContent(
@@ -1469,7 +1528,13 @@ function DropdownMenuPopover({
   const hasOverflow = useMenuOverflow(listRef, menuContent, popover.isOpen);
 
   // The header and footer sit beside the menu inside the popover, never inside
-  // the role="menu" element: a menu holds only its rows.
+  // the role="menu" element: a menu holds only its rows. The surface host
+  // follows the menu, so a sub-menu with a header or footer renders beside the
+  // menu too; while such a sub-menu's drilled-in view shows there, the menu and
+  // the regions step aside (STEPS_ASIDE_FOR_VIEW).
+  const surfaceHostElement = (
+    <div ref={attachSurfaceHost} {...stylex.props(styles.surfaceHost)} />
+  );
   const renderWithRegions = (menu: ReactNode): ReactNode =>
     hasRegions ? (
       <div
@@ -1482,7 +1547,7 @@ function DropdownMenuPopover({
           <div
             ref={headerRef}
             onKeyDown={handleRegionKeyDown}
-            {...stylex.props(styles.region)}>
+            {...stylex.props(styles.region, styles.stepsAsideForView)}>
             {header}
           </div>
         )}
@@ -1491,13 +1556,17 @@ function DropdownMenuPopover({
           <div
             ref={footerRef}
             onKeyDown={handleRegionKeyDown}
-            {...stylex.props(styles.region)}>
+            {...stylex.props(styles.region, styles.stepsAsideForView)}>
             {footer}
           </div>
         )}
+        {surfaceHostElement}
       </div>
     ) : (
-      menu
+      <>
+        {menu}
+        {surfaceHostElement}
+      </>
     );
 
   const triggerProps: DropdownMenuTriggerProps = {
@@ -1636,9 +1705,11 @@ function DropdownMenuPopover({
             )}>
             <MenuRegionsContext value={hasRegions}>
               <DropdownMenuContext value={contextValue}>
-                <DropdownMenuRootOpenContext value={isOpen}>
-                  {menuContent}
-                </DropdownMenuRootOpenContext>
+                <DropdownMenuSurfaceContext value={surfaceValue}>
+                  <DropdownMenuRootOpenContext value={isOpen}>
+                    {menuContent}
+                  </DropdownMenuRootOpenContext>
+                </DropdownMenuSurfaceContext>
               </DropdownMenuContext>
             </MenuRegionsContext>
           </div>,

package/src/DropdownMenu/DropdownMenuContext.public.test.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuContext.public.test.ts
+ * @input The DropdownMenu barrel and its public `DropdownMenuContextValue`
+ * @output Guards that the menu context keeps its members and that the internal
+ *   surface context a sub-menu with a header or footer reads is not exported
+ * @position Public API test guarding @astryxdesign/core/DropdownMenu
+ */
+
+import {describe, expect, expectTypeOf, it} from 'vitest';
+import * as dropdownMenu from './index';
+import type {DropdownMenuContextValue} from './index';
+
+describe('DropdownMenu public context', () => {
+  it('keeps its members and exports no surface context', () => {
+    expectTypeOf<keyof DropdownMenuContextValue>().toEqualTypeOf<
+      'closeMenu' | 'menuSize' | 'drillIn' | 'menuLabel'
+    >();
+    expect('DropdownMenuSurfaceContext' in dropdownMenu).toBe(false);
+  });
+});

package/src/DropdownMenu/DropdownMenuContext.tsx

@@ -45,7 +45,10 @@ export interface DropdownMenuDrillIn {
   viewStack: ReadonlyArray<string>;
   /** The element a shown view renders its rows into (a portal target). */
   host: HTMLElement | null;
-  /** Show a sub-menu's view in place of the current rows. */
+  /**
+   * Show a sub-menu's view in place of the current rows. A view with a header
+   * or footer renders into the root's surface host instead of `host`.
+   */
   push: (viewId: string) => void;
   /** Return to the rows the shown view replaced. */
   pop: () => void;
@@ -65,6 +68,41 @@ export interface DropdownMenuContextValue {
   menuLabel?: string;
 }
 
+/**
+ * The root's surface host. The root owns the element through a ref; this
+ * object is new whenever a new element attaches, so a sub-menu re-renders
+ * into it.
+ */
+export interface DropdownMenuSurfaceHost {
+  /** The host element, or `null` before it attaches. */
+  getElement: () => HTMLElement | null;
+}
+
+/** What a sub-menu with a header or footer needs from the root. Internal. */
+export interface DropdownMenuSurfaceValue {
+  /**
+   * An element inside the root's popover but outside every `role="menu"`
+   * element, where such a sub-menu renders its surface (its flyout layer, or
+   * its drilled-in view, while which the root's menu and regions step aside).
+   */
+  host: DropdownMenuSurfaceHost;
+  /**
+   * The root menu's `id`, which a sub-menu's menu in the host names so the
+   * press model counts it, and only it, as nested in the root.
+   */
+  ownerId: string;
+  /** The root's resolved `menuMaxHeight`, which a drilled-in view caps at. */
+  menuMaxHeight?: string;
+}
+
+/**
+ * The root's surface; `null` under a root with none (ContextMenu). Internal,
+ * off the public menu context, and layer-scoped, so each flyout re-provides it.
+ */
+export const DropdownMenuSurfaceContext =
+  createLayerScopedContext<DropdownMenuSurfaceValue | null>(null);
+DropdownMenuSurfaceContext.displayName = 'DropdownMenuSurfaceContext';
+
 /**
  * Whether the root menu of this layer tree is open; internal companion to
  * `DropdownMenuContext`, on its own unexported context so the public

package/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs

@@ -67,6 +67,18 @@ export const docs = {
         "How the sub-menu shows its rows. 'flyout' opens them beside the row; 'drill-in' replaces the menu's rows with them and a Back row, in the same box; 'adaptive' drills in when a finger opened the menu (a coarse pointer, decided when the menu opened) and flies out otherwise.",
       default: "'adaptive'",
     },
+    {
+      name: 'header',
+      type: 'ReactNode',
+      description:
+        'Content above the sub-menu\'s rows and outside its menu, a field that filters them, say. It keeps its own keys and presses. With a header or footer the sub-menu\'s surface (the flyout, or the drilled-in view on a phone) is a modal dialog named by the row, beside the menu rather than inside it: the row says aria-haspopup="dialog", Tab and Shift+Tab move through the header, the rows and the footer and wrap, Escape returns to the row, and a pointer leaving the flyout closes it only once focus leaves too. A ContextMenu does not show it.',
+    },
+    {
+      name: 'footer',
+      type: 'ReactNode',
+      description:
+        "Content below the sub-menu's rows and outside its menu, a door to where the options are managed, say. Same rules as header.",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -77,7 +89,7 @@ export const docs = {
       name: 'ref',
       type: 'React.Ref<HTMLElement>',
       description:
-        'Ref forwarded to the trigger row, the element carrying role="menuitem" and aria-haspopup="menu".',
+        'Ref forwarded to the trigger row, the element carrying role="menuitem" and aria-haspopup="menu" ("dialog" with a header or footer).',
     },
   ],
 };
@@ -100,6 +112,9 @@ export const docsDense = {
     onOpenChange: 'called when flyout opens/closes',
     presentation:
       "'flyout' beside the row | 'drill-in' replaces the rows + Back row | 'adaptive' (default) drills in on a coarse pointer",
+    header:
+      'content above the rows, outside the menu; surface becomes a modal dialog named by the row (Tab wraps, Escape returns to the row)',
+    footer: 'content below the rows, outside the menu; same rules as header',
     xstyle: 'StyleX styles for the trigger row',
     ref: 'ref to the trigger row (role="menuitem")',
   },