@astryxdesign/core 0.7.2 → 0.7.3-canary.0bf23bd

package/src/DateInput/DateInput.tsx

@@ -79,6 +79,18 @@ import {
 import {useDevWarning} from '../hooks/useDevWarning';
 
 const styles = stylex.create({
+  // The shared disabled style drops the focus ring; restore it while this
+  // field's own input holds focus (spec:AST-085 FR6). Defaults repeat it.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   iconButton: {
     display: 'flex',
     alignItems: 'center',
@@ -241,13 +253,13 @@ export interface DateInputProps 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 field stays focusable (via `aria-disabled`)
+   * `isDisabled`, the field shows a tooltip with this text on hover and
+   * keyboard focus, and the field's focusable controls are described by it,
    * so the reason is discoverable by keyboard and assistive technology.
    * Typing and calendar activation stay 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
    * ```
@@ -537,11 +549,11 @@ function PointerDateField({
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
-  // the text input stays perceivable via aria-disabled instead of the disabled
-  // attribute. Typing is blocked with readOnly and value mutation guards;
-  // calendar activation is blocked by the isEffectivelyDisabled guards. Only
+  // A disabled or busy field never renders native `disabled` (spec:AST-085
+  // FR1): the input and calendar button stay focusable via aria-disabled.
+  // Typing is blocked with readOnly and value mutation guards; calendar
+  // activation is blocked by the isEffectivelyDisabled guards. The
+  // disabled-reason tooltip's listeners attach to the input container. Only
   // the persistent isDisabled state (not the transient busy state) surfaces a
   // reason.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
@@ -703,8 +715,8 @@ function PointerDateField({
   // Handle input text change - update immediately if valid and allowed
   const handleInputChange = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
-      // With a disabledMessage the input drops `disabled` for focusability, so
-      // guard value mutation explicitly (readOnly also blocks typing).
+      // The input is never natively disabled (spec:AST-085 FR1), so guard
+      // value mutation explicitly (readOnly also blocks typing).
       if (isEffectivelyDisabled) {
         return;
       }
@@ -733,6 +745,11 @@ function PointerDateField({
     if (pendingInput === null) {
       return;
     }
+    // Disabled or busy: keep the value, drop the draft (spec:AST-085 FR2).
+    if (isEffectivelyDisabled) {
+      setPendingInput(null);
+      return;
+    }
 
     if (!pendingInput.trim()) {
       if (value !== undefined) {
@@ -750,7 +767,14 @@ function PointerDateField({
       }
     }
     setPendingInput(null);
-  }, [pendingInput, value, fireChange, isDateDisabled, locale]);
+  }, [
+    pendingInput,
+    isEffectivelyDisabled,
+    value,
+    fireChange,
+    isDateDisabled,
+    locale,
+  ]);
 
   // Handle blur - validate, check constraints, and clear pending input
   const handleBlur = useCallback(() => {
@@ -808,6 +832,7 @@ function PointerDateField({
           inputWrapperStyles.base,
           sizeStyles[size],
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -823,7 +848,11 @@ function PointerDateField({
       <button
         type="button"
         onClick={handleToggle}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
+        // A tab stop while disabled too, so it carries the reason (FR5).
+        aria-describedby={
+          showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
+        }
         aria-label={
           popover.isOpen
             ? t('@astryx.dateInput.toggleCalendarClose')
@@ -858,16 +887,15 @@ function PointerDateField({
         value={displayValue}
         onChange={handleInputChange}
         onBlur={chainEventHandlers(handleBlur, onBlurProp)}
-        onClick={chainEventHandlers(handleInputClick, onClickProp)}
+        onClick={
+          isEffectivelyDisabled
+            ? undefined
+            : chainEventHandlers(handleInputClick, onClickProp)
+        }
         onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
         placeholder={placeholder}
-        // With a disabledMessage the input keeps focusability via
-        // aria-disabled so the reason is focus-discoverable; typing is
-        // blocked with readOnly and the mutation guards, and calendar
-        // activation is blocked by the isEffectivelyDisabled guards.
-        disabled={isEffectivelyDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={showsDisabledMessage || undefined}
+        aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
+        readOnly={isEffectivelyDisabled || undefined}
         aria-labelledby={
           ariaLabelledByProp != null
             ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateInput/DateInputTouch.test.tsx

@@ -554,11 +554,32 @@ describe('DateInput — field parity', () => {
         onChange={() => {}}
       />,
     );
-    expect(field()).toBeDisabled();
+    // Focusable, never natively disabled (AST-085 FR1), and still inert.
+    expect(field()).not.toHaveAttribute('disabled');
+    expect(field()).toHaveAttribute('aria-disabled', 'true');
+    field().focus();
+    expect(field()).toHaveFocus();
     fireEvent.click(field());
+    fireEvent.keyDown(field(), {key: 'Enter'});
+    expect(field()).toHaveAttribute('aria-expanded', 'false');
     expect(screen.queryByRole('grid')).not.toBeInTheDocument();
   });
 
+  it('does not call a caller onClick while disabled (AST-085 FR2)', () => {
+    const onClick = vi.fn();
+    render(
+      <DateInput
+        nativePicker="never"
+        label="Ship date"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(field());
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
   it('stays focusable and explains itself when disabled with a reason', () => {
     render(
       <DateInput

package/src/DateInput/NativeDateField.test.tsx

@@ -601,12 +601,38 @@ describe('DateInput nativePicker', () => {
     await act(async () => resolveAction());
   });
 
-  it('disables the control and its toggle when isDisabled', () => {
+  it('keeps a disabled control focusable and its toggle inert (AST-085 FR1, FR2)', () => {
     stubPointer(true);
     render(<DateInput label="Date" isDisabled onChange={() => {}} />);
 
-    expect(getInput()).toBeDisabled();
-    expect(screen.getByLabelText('Open calendar')).toBeDisabled();
+    const input = getInput();
+    expect(input).not.toHaveAttribute('disabled');
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+    input.focus();
+    expect(input).toHaveFocus();
+    const toggle = screen.getByLabelText('Open calendar');
+    expect(toggle).not.toHaveAttribute('disabled');
+    expect(toggle).toHaveAttribute('aria-disabled', 'true');
+    const showPicker = vi.fn();
+    Object.defineProperty(input, 'showPicker', {value: showPicker});
+    fireEvent.click(toggle);
+    expect(showPicker).not.toHaveBeenCalled();
+  });
+
+  it('does not call a caller onClick while disabled (AST-085 FR2)', () => {
+    stubPointer(true);
+    const onClick = vi.fn();
+    render(
+      <DateInput
+        label="Date"
+        isDisabled
+        onClick={onClick}
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(getInput());
+    expect(onClick).not.toHaveBeenCalled();
   });
 
   it('ignores a change while disabled', () => {

package/src/DateInput/NativeDateField.tsx

@@ -82,6 +82,17 @@ import {
 import {chainEventHandlers} from '../utils/chainEventHandlers';
 
 const styles = stylex.create({
+  // Same as DateInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   wrapper: {
     gap: spacingVars['--spacing-2'],
   },
@@ -323,9 +334,10 @@ export function NativeDateField({
   // platform picker from its input.
   const isEffectivelyDisabled = isDisabled || isLoading;
 
-  // Disabled-reason tooltip, same contract as the other two surfaces: a
-  // disabled control swallows pointer events, so the listeners attach to the
-  // wrapper and the input stays focusable via aria-disabled.
+  // Same contract as the other two surfaces: a disabled field never renders
+  // native `disabled` (spec:AST-085 FR1); the input stays focusable via
+  // aria-disabled and readOnly. The disabled-reason tooltip's listeners
+  // attach to the wrapper.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -582,6 +594,7 @@ export function NativeDateField({
           sizeStyles[size],
           styles.wrapper,
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -597,7 +610,7 @@ export function NativeDateField({
       <button
         type="button"
         onClick={openPicker}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.dateInput.openCalendar')}
         tabIndex={-1}
         {...stylex.props(
@@ -615,6 +628,7 @@ export function NativeDateField({
       <span {...stylex.props(styles.slot)}>
         <input
           {...controlProps}
+          onClick={isEffectivelyDisabled ? undefined : controlProps.onClick}
           ref={mergedInputRef}
           id={id}
           type="date"
@@ -626,9 +640,8 @@ export function NativeDateField({
           onBlur={chainEventHandlers(handleBlur, onBlurProp)}
           min={min}
           max={max}
-          disabled={isEffectivelyDisabled && !showsDisabledMessage}
-          aria-disabled={showsDisabledMessage ? 'true' : undefined}
-          readOnly={showsDisabledMessage || undefined}
+          aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
+          readOnly={isEffectivelyDisabled || undefined}
           aria-labelledby={
             ariaLabelledByProp != null
               ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateInput/TouchDateField.tsx

@@ -166,6 +166,17 @@ const sizeStyles = stylex.create({
 });
 
 const styles = stylex.create({
+  // Same as DateInput's: the focus ring for a focused disabled field.
+  disabledFocusRing: {
+    borderColor: {
+      default: colorVars['--color-border-emphasized'],
+      ':has(input:focus)': colorVars['--color-accent'],
+    },
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+    },
+  },
   // ---- the closed field ----
   wrapper: {
     gap: spacingVars['--spacing-2'],
@@ -620,11 +631,11 @@ export function TouchDateField({
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
 
-  // Disabled-reason tooltip, same contract as DateInput: a disabled control
-  // swallows pointer events, so the listeners attach to the wrapper and the
-  // input stays focusable via aria-disabled rather than the disabled
-  // attribute. Only the persistent disabled state surfaces a reason, never
-  // the transient busy one.
+  // Same contract as DateInput: a disabled or busy field never renders native
+  // `disabled` (spec:AST-085 FR1); the input stays focusable via
+  // aria-disabled. The disabled-reason tooltip's listeners attach to the
+  // wrapper. Only the persistent disabled state surfaces a reason, never the
+  // transient busy one.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1213,6 +1224,7 @@ export function TouchDateField({
           sizeStyles[size],
           styles.wrapper,
           isEffectivelyDisabled && inputWrapperStyles.disabled,
+          isEffectivelyDisabled && styles.disabledFocusRing,
           status && inputStatusBorderStyles[status.type],
           status &&
             !isEffectivelyDisabled &&
@@ -1228,7 +1240,7 @@ export function TouchDateField({
       <button
         type="button"
         onClick={openSheet}
-        disabled={isEffectivelyDisabled}
+        aria-disabled={isEffectivelyDisabled || undefined}
         aria-label={t('@astryx.dateInput.openCalendar')}
         tabIndex={-1}
         {...stylex.props(
@@ -1259,11 +1271,14 @@ export function TouchDateField({
         readOnly
         inputMode="none"
         onChange={() => {}}
-        onClick={chainEventHandlers(openSheet, onClickProp)}
+        onClick={
+          isEffectivelyDisabled
+            ? undefined
+            : chainEventHandlers(openSheet, onClickProp)
+        }
         onKeyDown={chainEventHandlers(handleInputKeyDown, onKeyDownProp)}
         placeholder={placeholder}
-        disabled={isEffectivelyDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        aria-disabled={isEffectivelyDisabled ? 'true' : undefined}
         aria-labelledby={
           ariaLabelledByProp != null
             ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)

package/src/DateRangeInput/DateRangeInput.spec.md

@@ -90,12 +90,12 @@ preset-list anatomy and its additive theming surface.
 
 ### Representative states
 
-| State             | Required invariant                                                                                                                          | Allowed variation       |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| No presets        | No preset group or preset-button target renders.                                                                                            | Calendar configuration  |
-| Presets, no match | Every button carries the preset target with no selected state.                                                                              | Preset count and labels |
-| Applied preset    | The matching button carries `aria-current="true"` and the target's selected state.                                                          | Selected range          |
-| Disabled preset   | A preset that violates an endpoint date constraint or a range-span constraint is natively disabled and carries the target's disabled state. | Constraint source       |
+| State             | Required invariant                                                                                                                                    | Allowed variation       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| No presets        | No preset group or preset-button target renders.                                                                                                      | Calendar configuration  |
+| Presets, no match | Every button carries the preset target with no selected state.                                                                                        | Preset count and labels |
+| Applied preset    | The matching button carries `aria-current="true"` and the target's selected state.                                                                    | Selected range          |
+| Disabled preset   | A preset that violates an endpoint date constraint or a range-span constraint is disabled per `spec:AST-085` and carries the target's disabled state. | Constraint source       |
 
 ### Transformation and precedence order
 
@@ -120,8 +120,8 @@ No new performance or resource constraint is introduced.
 - **AR2 — Current state.** The applied preset remains exposed with
   `aria-current="true"`; theme state reflection is additive.
 - **AR3 — Disabled state.** A preset that violates an endpoint date constraint or
-  a range-span constraint remains natively disabled; theme state reflection does
-  not replace that behavior.
+  a range-span constraint is disabled and stays focusable (`spec:AST-085`); theme
+  state reflection does not replace that behavior.
 
 ## Design relationships
 
@@ -172,11 +172,11 @@ No new performance or resource constraint is introduced.
 
 ## Verification map
 
-| Contract            | Verification                                                               | Representative states                                                  | Mutation or failure expectation                                             | Audit section                  |
-| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ |
-| FR1, FR2, AR1–AR3   | `DateRangeInput.test.tsx`                                                  | no match, applied preset, endpoint-invalid preset, span-invalid preset | Semantics or state attributes disappear                                     | `audit:DateRangeInput/presets` |
-| FR3, FR4            | `DateRangeInput.test.tsx`, `themingTargets.test.ts`, generated probe theme | group target, selected button, disabled button                         | Target class/state is missing, undocumented, or placed on the wrong element | `audit:DateRangeInput/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                              | all documented anatomy                                                 | Target ownership or anatomy names drift                                     | `audit:DateRangeInput/theming` |
+| Contract            | Verification                                                                      | Representative states                                                  | Mutation or failure expectation                                             | Audit section                  |
+| ------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ |
+| FR1, FR2, AR1–AR3   | `DateRangeInput.test.tsx`; disabled-preset focusability (AR3) pending conformance | no match, applied preset, endpoint-invalid preset, span-invalid preset | Semantics or state attributes disappear                                     | `audit:DateRangeInput/presets` |
+| FR3, FR4            | `DateRangeInput.test.tsx`, `themingTargets.test.ts`, generated probe theme        | group target, selected button, disabled button                         | Target class/state is missing, undocumented, or placed on the wrong element | `audit:DateRangeInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                     | all documented anatomy                                                 | Target ownership or anatomy names drift                                     | `audit:DateRangeInput/theming` |
 
 ## Decision log
 

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.