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

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -23,6 +23,8 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
 // made every role+name query compute ~85 accessible names through jsdom's
 // slow getComputedStyle (~450ms per query). See fastRoleQueries.ts.
 import {getButton, queryButton} from '../__tests__/fastRoleQueries';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {DateRangeInput} from './DateRangeInput';
 import type {DateRange} from './DateRangeInput';
 import {Icon} from '../Icon';
@@ -155,7 +157,46 @@ describe('DateRangeInput', () => {
       />,
     );
     const trigger = getButton(/Range/);
-    expect(trigger).toBeDisabled();
+    expect(trigger).not.toHaveAttribute('disabled');
+    expect(trigger).toHaveAttribute('aria-disabled', 'true');
+    trigger.focus();
+    expect(trigger).toHaveFocus();
+  });
+
+  it('restores the focus ring on a focused disabled field (AST-085 FR6)', () => {
+    // The same declarations as the field's ring style compile to the same
+    // atomic classes.
+    const ringClasses = stylex
+      .props(
+        stylex.create({
+          ring: {
+            borderColor: {
+              default: colorVars['--color-border-emphasized'],
+              ':focus-within': colorVars['--color-accent'],
+            },
+            boxShadow: {
+              default: 'none',
+              ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+            },
+          },
+        }).ring,
+      )
+      .className!.split(' ')
+      // Keep the atomic classes, not the dev-only debug name.
+      .filter(name => !name.includes('__'));
+    render(
+      <DateRangeInput
+        label="Range"
+        isDisabled
+        value={null}
+        onChange={() => {}}
+      />,
+    );
+    // The shared disabled style alone drops these :focus-within declarations.
+    const wrapper = getButton(/Range/).parentElement!;
+    for (const name of ringClasses) {
+      expect(wrapper).toHaveClass(name);
+    }
   });
 
   it('is not disabled by default', () => {
@@ -272,7 +313,8 @@ describe('DateRangeInput', () => {
         onChange={() => {}}
       />,
     );
-    expect(getButton('Open calendar')).toBeDisabled();
+    expect(getButton('Open calendar')).not.toHaveAttribute('disabled');
+    expect(getButton('Open calendar')).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('renders with size="lg"', () => {
@@ -526,7 +568,8 @@ describe('DateRangeInput', () => {
       );
 
       const preset = getButton('Last 7 days');
-      expect(preset).toBeDisabled();
+      expect(preset).not.toHaveAttribute('disabled');
+      expect(preset).toHaveAttribute('aria-disabled', 'true');
       fireEvent.click(preset);
       expect(handleChange).not.toHaveBeenCalled();
     });
@@ -544,7 +587,8 @@ describe('DateRangeInput', () => {
       );
 
       const preset = getButton('Last 7 days');
-      expect(preset).toBeDisabled();
+      expect(preset).not.toHaveAttribute('disabled');
+      expect(preset).toHaveAttribute('aria-disabled', 'true');
       fireEvent.click(preset);
       expect(handleChange).not.toHaveBeenCalled();
     });
@@ -562,7 +606,8 @@ describe('DateRangeInput', () => {
       );
 
       const preset = getButton('Last 7 days');
-      expect(preset).toBeDisabled();
+      expect(preset).not.toHaveAttribute('disabled');
+      expect(preset).toHaveAttribute('aria-disabled', 'true');
       fireEvent.click(preset);
       expect(handleChange).not.toHaveBeenCalled();
     });
@@ -590,7 +635,7 @@ describe('DateRangeInput', () => {
 
       const getRangeCallsBeforeClick = getRange.mock.calls.length;
       const preset = getButton('Allowed range');
-      expect(preset).not.toBeDisabled();
+      expect(preset).not.toHaveAttribute('aria-disabled');
       fireEvent.click(preset);
       expect(handleChange).toHaveBeenCalledWith(range);
       expect(getRangeCallsAtChange).toBe(getRangeCallsBeforeClick);
@@ -613,7 +658,10 @@ describe('DateRangeInput', () => {
     // accessibility tree; use hidden: true to find it.
     const h = {hidden: true} as const;
 
-    function renderDisabled(props?: {disabledMessage?: string}) {
+    function renderDisabled(props?: {
+      disabledMessage?: string;
+      onClick?: () => void;
+    }) {
       return render(
         <DateRangeInput
           label="Range"
@@ -699,11 +747,22 @@ describe('DateRangeInput', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'false');
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
-      renderDisabled();
+    it('blocks activation and a caller onClick when disabled without a reason (AST-085 FR1, FR2)', async () => {
+      const user = userEvent.setup();
+      const onClick = vi.fn();
+      renderDisabled({onClick});
       const trigger = getButton(/Range:/);
-      expect(trigger).toBeDisabled();
-      expect(trigger).not.toHaveAttribute('aria-disabled');
+      expect(trigger).not.toHaveAttribute('disabled');
+      await user.click(trigger);
+      await user.keyboard('{Enter}');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(onClick).not.toHaveBeenCalled();
+    });
+
+    it('blocks the calendar button while disabled (AST-085 FR2)', () => {
+      renderDisabled();
+      fireEvent.click(getButton('Open calendar'));
+      expect(getButton(/Range:/)).toHaveAttribute('aria-expanded', 'false');
     });
   });
 });
@@ -988,13 +1047,19 @@ describe('DateRangeInput range-span forwarding', () => {
     fireEvent.click(getButton('Open calendar'));
 
     // Before a start is picked, a far-off day is selectable.
-    expect(dayButton('2026-01-20')).not.toBeDisabled();
+    expect(dayButton('2026-01-20')).not.toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
 
     fireEvent.click(dayButton('2026-01-10') as HTMLButtonElement);
 
     // A 7-day window spans start ± 6 days: Jan 16 is the edge, Jan 17 is out.
-    expect(dayButton('2026-01-16')).not.toBeDisabled();
-    expect(dayButton('2026-01-17')).toBeDisabled();
+    expect(dayButton('2026-01-16')).not.toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+    expect(dayButton('2026-01-17')).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('disables a preset whose range violates the span cap', () => {
@@ -1030,9 +1095,10 @@ describe('DateRangeInput range-span forwarding', () => {
     // The 3-day preset fits the 7-day cap; the 30-day preset can't be committed.
     const withinCap = getButton('Last 3 days');
     const overCap = getButton('Last 30 days');
-    expect(withinCap).not.toBeDisabled();
+    expect(withinCap).not.toHaveAttribute('aria-disabled');
     expect(withinCap).not.toHaveAttribute('data-disabled');
-    expect(overCap).toBeDisabled();
+    expect(overCap).not.toHaveAttribute('disabled');
+    expect(overCap).toHaveAttribute('aria-disabled', 'true');
     expect(overCap).toHaveClass('astryx-date-range-input-preset');
     expect(overCap).toHaveAttribute('data-disabled', 'disabled');
 

package/src/DateRangeInput/DateRangeInput.tsx

@@ -97,6 +97,18 @@ export type {
 } from '../Field';
 
 const styles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while a
+  // control inside the field holds focus (spec:AST-085 FR6). Defaults repeat it.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':focus-within': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':focus-within': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   trigger: {
     display: 'block',
     flex: 1,
@@ -309,12 +321,12 @@ export interface DateRangeInputProps extends Omit<
   /**
    * Explains why the input is disabled. When set together with
    * `isDisabled`, the input shows a tooltip with this text on hover and
-   * keyboard focus, and the trigger stays focusable (via `aria-disabled`)
-   * so the reason is discoverable by keyboard and assistive technology.
-   * Activation stays blocked.
+   * keyboard focus, and the trigger is described by it, so the reason is
+   * discoverable by keyboard and assistive technology. Activation stays
+   * blocked.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the
+   * reason is tied to the field.
    *
    * @example
    * ```
@@ -546,12 +558,12 @@ export function DateRangeInput({
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isEffectivelyDisabled
-  // guard in handleToggle. Only the persistent isDisabled state (not the
-  // transient busy state) surfaces a reason.
+  // A disabled or busy field never renders native `disabled` (spec:AST-085
+  // FR1): its buttons stay focusable via aria-disabled, and activation is
+  // blocked by the isEffectivelyDisabled guard in handleToggle. The
+  // disabled-reason tooltip's listeners attach to the trigger container. Only
+  // the persistent isDisabled state (not the transient busy state) surfaces a
+  // reason.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -695,6 +707,7 @@ export function DateRangeInput({
             inputWrapperStyles.base,
             sizeStyles[size],
             isEffectivelyDisabled && inputWrapperStyles.disabled,
+            isEffectivelyDisabled && styles.disabledFocusRing,
             status && inputStatusBorderStyles[status.type],
             status &&
               !isEffectivelyDisabled &&
@@ -708,7 +721,7 @@ export function DateRangeInput({
         <button
           type="button"
           onClick={handleToggle}
-          disabled={isEffectivelyDisabled}
+          aria-disabled={isEffectivelyDisabled || undefined}
           aria-label={
             popover.isOpen
               ? t('@astryx.dateInput.toggleCalendarClose')
@@ -734,12 +747,14 @@ export function DateRangeInput({
           ref={triggerButtonRef}
           id={id}
           type="button"
-          onClick={chainEventHandlers(handleToggle, onClickProp)}
-          // With a disabledMessage the trigger keeps focusability via
-          // aria-disabled so the reason is focus-discoverable; activation is
-          // still blocked by the isEffectivelyDisabled guard in handleToggle.
-          disabled={isEffectivelyDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}
+          // The browser still dispatches a click on an aria-disabled button,
+          // so a caller's onClick is skipped too (spec:AST-085 FR2).
+          onClick={
+            isEffectivelyDisabled
+              ? undefined
+              : chainEventHandlers(handleToggle, onClickProp)
+          }
+          aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
           // A caller aria-label replaces the trigger's name; a caller
           // aria-labelledby is read after it (label and selected range).
           aria-label={ariaLabelProp ?? triggerAriaLabel}
@@ -807,8 +822,13 @@ export function DateRangeInput({
                     // marked with aria-current (not aria-selected, a listbox
                     // concept that contradicted the Tab interaction) (forms-5).
                     aria-current={isActive ? 'true' : undefined}
-                    disabled={isPresetDisabled}
-                    onClick={() => handleRangeSelect(presetRange)}
+                    // Focusable while disabled (AR3, spec:AST-085 FR1).
+                    aria-disabled={isPresetDisabled || undefined}
+                    onClick={() => {
+                      if (!isPresetDisabled) {
+                        handleRangeSelect(presetRange);
+                      }
+                    }}
                     {...mergeProps(
                       themeProps('date-range-input-preset', {
                         selected: isActive ? 'selected' : null,

package/src/Dialog/Dialog.test.tsx

@@ -286,6 +286,45 @@ describe('Dialog', () => {
     });
   });
 
+  describe('a cancel from inside the dialog', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed (Escape, or Cancel in the chooser). It reaches the <dialog>
+    // like a close request but is not one.
+    function DialogWithFilePicker({onOpenChange}: {onOpenChange: () => void}) {
+      return (
+        <Dialog isOpen onOpenChange={onOpenChange} aria-label="Upload">
+          <input type="file" aria-label="Picture" />
+        </Dialog>
+      );
+    }
+
+    it('stays open when a file picker inside it is dismissed', () => {
+      const onOpenChange = vi.fn();
+      render(<DialogWithFilePicker onOpenChange={onOpenChange} />);
+
+      const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+      screen.getByLabelText('Picture').dispatchEvent(fromPicker);
+
+      expect(onOpenChange).not.toHaveBeenCalled();
+      expect(fromPicker.defaultPrevented).toBe(false);
+    });
+
+    it('still closes on its own close request', () => {
+      const onOpenChange = vi.fn();
+      render(<DialogWithFilePicker onOpenChange={onOpenChange} />);
+
+      screen
+        .getByLabelText('Picture')
+        .dispatchEvent(new Event('cancel', {bubbles: true, cancelable: true}));
+      screen
+        .getByRole('dialog')
+        .dispatchEvent(new Event('cancel', {cancelable: true}));
+
+      expect(onOpenChange).toHaveBeenCalledTimes(1);
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+  });
+
   describe('IME composition', () => {
     // A CJK user presses Escape to cancel a half-formed character several times
     // a sentence. jsdom models neither composition nor the close watcher, so

package/src/Dialog/Dialog.tsx

@@ -643,11 +643,16 @@ export function Dialog({
   // Escape presses the stack owns never arrive here — it preventDefault()s
   // those, which suppresses the close watcher.
   //
-  // Always preventDefault so the browser cannot close a controlled <dialog>
-  // behind React's back, then answer the request with the stack's own rules:
-  // only the top-most layer dismisses, a `required` dialog swallows it, and
-  // nothing dismisses while an IME composition is in progress.
+  // A `cancel` that bubbles up from inside is not a close request for this
+  // dialog: a file input fires one when its picker is dismissed. It is left
+  // alone. Otherwise always preventDefault so the browser cannot close a
+  // controlled <dialog> behind React's back, then answer the request with the
+  // stack's own rules: only the top-most layer dismisses, a `required` dialog
+  // swallows it, and nothing dismisses while an IME composition is in progress.
   const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
+    if (event.target !== event.currentTarget) {
+      return;
+    }
     event.preventDefault();
     if (!shouldDismissOnCloseRequest()) {
       return;

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);
+  });
+});